debrief-coding

Before asking, read User Questions.

Debrief Coding

Read .cache/codemap/logs/ JSONL, analyse use, write diagnostic report. Include recursive claude/, codex/, direct/ shards; keep legacy flat records unattributed. Codex records runtime-scoped CLI/tool shards, no skill starts; missing skill telemetry + cross-layer joins are evidence gaps.

NOT for: installation/integration health (use $codemap-py:integration audit); index build or structural query (use $codemap-py:scan-codebase or $codemap-py:query-code).

Runtime note

Codex has no bin/ PATH entry or plugin-root variable. Resolve installed root once, substitute for PLUGIN_ROOT, retain in reasoning; shell state doesn't persist. Telemetry otherwise matches Claude: local JSONL under .cache/codemap/logs/.

Flags

• --since <YYYY-MM-DD>: records on/after date; default all.
• --session <id>: one session UUID.
• --anonymize: run anonymize.py; pseudonymize qualified names and shard stems, preserve topology, store salt only at .cache/codemap/logs/.salt.
• --output <path>: report path; default .reports/codemap/debrief-<YYYY-MM-DD>.md.

Workflow

1. Verify logs

find .cache/codemap/logs -type f -name '*.jsonl' -print 2>/dev/null

No files: stop: "No codemap telemetry found. Run any $codemap-py:* skill or codemap-py query/index command to start collecting logs." Collect every matching shard recursively; cli_<session>.jsonl, skills_<session>.jsonl, tools_<session>.jsonl live below each runtime directory. Flat shards remain unattributed; never infer Claude from tool names. token_measurement unavailable — host hooks expose no token usage.

2. Anonymize when requested

python PLUGIN_ROOT/bin/anonymize.py --input .cache/codemap/logs --out-dir .cache/codemap/export

Use only anonymized copies after this step; never mix with raw data. Separated from .salt; never target log directory. With no shard, stop: "no CLI or skill logs found — cannot produce an anonymized report." With one layer, anonymize it, report the gap.

3. Read and filter records

Read every CLI, skill, tool shard recursively; one file is incomplete. Each line is JSON. Filter ts by --since, session by --session; empty filter in one layer is expected — UUID can be absent there.

• CLI: ts, layer, runtime, v, session, cmd, argv, result (count, query_complete, completeness_reason, stale, method, not_covered, error; index also trigger, changed_count, incremental, stale_before, result_currency), timing_ms, optional stderr/exit_code.
• Skill: ts, layer, runtime, v, session, skill, event, intent, hook_session.
• Tool: ts, layer, runtime, v, session, skill, event, tool, target.

4. Analyse

Exclude source: "bench" and CLI records with empty cmd from organic stats; report count as "scripted/polluted records excluded: N". When present, group headline statistics by distinct v, overall, runtime, unattributed legacy records.

• CLI: invocations; success/error (exit_code: 0 success; non-zero error; absent success unless result.error); completeness reasons; subcommands; median/p95/max timing_ms; non-empty not_covered fraction; top five error prefixes; stale fraction.
• Skill: starts by name, sessions, first/last timestamp.
• Cross-layer: linked skill→N CLI chains, average calls per skill session, refresh triggers, changed-count distribution, index-only sessions, incomplete/degraded fractions; legacy provenance unknown.

Join tool searches/reads to a complete (query_complete: true) CLI answer for the same module within the window: a match is an avoidance event, not an incorrect answer.

python PLUGIN_ROOT/bin/join_avoidance.py --logs .cache/codemap/logs --window-min 10 --json

High avoidance means guard/context/model dead-chain risk. Preserve per_runtime and unattributed; report count/rate in Overview and flagged modules when non-zero. Never claim measured token savings or live fresh-session activation.

5. Write report

Default output is .reports/codemap/debrief-<YYYY-MM-DD>.md; use --output if supplied.

mkdir -p .reports/codemap

Include Overview (2–3 sentences), subcommand distribution, performance (median/p95/max), coverage gaps, top-five error patterns (none when clean), skill invocations, and session timeline (first/last, sessions; full chronology for --session). Print the path.

Security

Logs and salt are local. Never share .cache/codemap/logs/.salt; anonymized files are shareable without it.