Skills/postmortem/SKILL.md

name, description

name

description

postmortem

Use after a working session (or a `/boss` run) to grade how well the toolchain and the dispatched agents actually performed, and how many tokens the run spent. Reads the session's own Claude Code transcript + subagent logs + Workflow run logs, aggregates tokens/tool-health deterministically via a helper script, and writes a scored retrospective. Utility skill, user-invoked or orchestrator-invoked at run close; never a pipeline gate.

postmortem — grade the run

Violating the letter of these rules is violating the spirit.

Overview

Every session leaves a detailed flight recorder behind — the JSONL transcript under ~/.claude/projects/<slug>/<session>.jsonl, one sidechain log per dispatched subagent under <session>/subagents/, and for every Workflow run a per-agent summary in <session>/workflows/wf_*.json with raw per-agent transcripts under <session>/subagents/workflows/<runId>/. Nobody reads it. So the same expensive habits repeat: a subagent fleet that bounces BLOCKED, a tool loop with a 30% error rate, a cache-cold run that re-sends the full input on every turn. This skill turns that recorder into a graded retrospective: how well did the toolchain work, how effective were the agents, and how many tokens did it spend.

It is descriptive, not corrective. It produces a report and, where warranted, recommends filing tracker issues — it does not change code, baselines, or the pipeline.

When to Use / Skipping

Invoke:

• After a substantial interactive session, when you want to know where the time and tokens went.
• At the close of a /boss autonomous run, to grade the orchestrator's dispatch choices.
• When a run felt token-heavy or thrashy and you want the numbers.

Not a pipeline phase. Never a hard-gate. It reads logs; it never blocks a cycle.

The Iron Law

NUMBERS COME FROM THE SCRIPT, NEVER FROM MEMORY OR EYEBALLING THE LOG
REPORT TOKENS AS RAW COUNTS — NEVER CONVERT THEM TO A COST OR PRICE
NEVER READ ~/.ionos_token, .credentials.json, OR ANY SECRET FILE INTO CONTEXT
A GRADE WITHOUT A CITED METRIC IS AN OPINION — DROP IT
DEDUP TOKEN USAGE BY requestId — THE SCRIPT DOES THIS; DO NOT RE-SUM THE RAW LOG BY HAND

What the data does and does not contain

Read before interpreting, so the report never overclaims:

• Present: per-request usage (input / output / cache-creation / cache-read / server-tool counts), model, requestId, timestamps, every tool_use with its input, every tool_result with the authoritative is_error flag, skill invocations, slash commands, and a full separate transcript + agentType / description for each subagent. Workflow runs additionally carry a per-agent summary (stage label, model, a live token counter) in workflows/wf_*.json; the counter under-tracks vs. the deduped raw transcripts (~11% in the corpus behind issue #28), so the script treats the raw transcripts as authoritative and reports the counter only as reported_total_tokens for cross-checking.
• Absent: costUSD is always null; durationMs is always null. There is no metered cost in the log, so this skill does not compute one — it reports raw token counts (kept split by class: input / output / cache-creation / cache-read, plus a total_tokens sum). Wall-clock is derived from timestamp deltas and the report says so.

The streamed transcript repeats the same requestId across several assistant lines with an identical usage object. The helper script dedups per requestId; never sum the raw lines.

The Process

Step 1 — Run the aggregator

python3 <skill-dir>/scripts/postmortem.py [--session <id>] [--cwd <project>]

Defaults to the newest transcript in the current project's log dir — i.e. the session you are in (it will be flagged active, meaning totals are partial). To grade a finished run, pass its --session <uuid>.

The default log dir is derived from cwd (the path with / replaced by -), so a session run inside a git worktree resolves to a different slug than the primary clone, and after exiting a worktree the default again follows the current cwd. To grade a worktree run from the primary clone, pass --project-dir ~/.claude/projects/<worktree-slug> (or --file <path> to bypass slug derivation entirely).

The script emits one JSON object on stdout. That JSON — not the raw log — is your evidence base.

Step 2 — Read the JSON and grade three axes

Grade each axis on the cited numbers. A grade with no number behind it is an opinion; drop it.

1. Token spend & efficiency — totals.total_tokens, the main-vs-subagent split, the token breakdown (output share is the write-heavy signal), cache_hit_ratio (the dominant efficiency lever: below ~0.7 on a long session means cache-cold turns re-sending the full input), server_tools (web_search / web_fetch counts).
2. Toolchain health — tools.error_ratio and interrupted (the authoritative is_error signal), the tool mix (a Read / Edit / Bash imbalance hints at thrashing or re-reading), slash_commands such as /compact (context pressure).
3. Agent effectiveness — per subagent: terminal_status (DONE / DONE_WITH_CONCERNS / PARTIAL / BLOCKED / NEEDS_CONTEXT / unknown), total_tokens, and requests. A fleet that burned real tokens to return BLOCKED is the headline finding. Compare each agent's token spend to what it delivered. For Workflow runs, grade per stage instead: workflow_totals and each run's stages table (label-prefix grouping, e.g. all impl:N under impl) show where the run's spend concentrated; agents_untracked > 0 flags retried/dropped attempts. Schema-bound workflow stages carry no terminal_status — the workflow script's own aggregation already judged them.

Step 3 — Write the report

Write a Markdown report to the configured destination (see Output destination). Structure it as Output format below. Lead with the scorecard, support every grade with a number from the JSON, and keep the prose tight — this is a retrospective, not a transcript replay.

Step 4 — Surface, don't fix

Translate the sharpest findings into recommendations. Where a finding is a concrete, trackable defect (a subagent that reliably bounces BLOCKED, a tool loop with a runaway error rate), recommend filing it via the issue skill — name it, but do not file it yourself unless the user asks. This skill ends at the report.

Output destination

Resolve in this order:

1. --out <path> if the invoker passed one.
2. The project's post-mortem directory, if it has one (its CLAUDE.md project facts).
3. Default: docs/postmortems/<session-id-short>-<yyyy-mm-dd>.md under the project root, creating the directory if needed.

Also print a ≤200-word summary to the chat so the headline grade and token spend are visible without opening the file.

Output format

# Post-mortem — <session-id-short> (<date>)

**Scorecard**
| Axis | Grade | Headline metric |
|------|-------|-----------------|
| Token spend & efficiency | A–F | <total_tokens> total, cache hit <ratio> |
| Toolchain health  | A–F | <error_ratio>, <n> interrupts |
| Agent effectiveness | A–F | <k>/<n> agents DONE, <tokens> on subagents |

**Token spend**
<main vs subagent split; token breakdown by class (input / output /
cache-creation / cache-read); the one class that dominates and why>

**Toolchain**
<tool mix, error ratio + what the errors were, context-pressure
signals like /compact>

**Agents**
<per-subagent line: type — status — <total_tokens> — one-clause
verdict. Omit if no subagents were dispatched.>

**Recommendations**
<≤5 bullets. Each ties to a cited metric. Mark any that warrant
an `issue`.>

_Token counts are raw usage. Wall-clock is derived from timestamp
deltas, not metered._

If the session is flagged active, add one line at the top: "⚠️ Session still active — figures are partial."

Common Rationalisations

Excuse	Reality
"I'll just skim the transcript and tally the tokens"	The transcript repeats usage per streamed line under a shared requestId. Hand-summing double-counts. Run the script.
"Let me convert the tokens to a rough dollar figure"	Don't. There is no metered cost in the log and prices vary by plan; report raw token counts and let the reader price them if they want.
"Cache hit ratio of 0.5 is fine"	On a long session it means half the input was re-sent uncached. That is the single biggest efficiency lever — grade it.
"All agents returned, so effectiveness is an A"	"Returned" ≠ "succeeded". A BLOCKED agent that burned tens of thousands of tokens is a failure that still spent the budget. Read terminal_status.
"Let me also peek at the IONOS token to check the endpoint"	Never. Secret files are out of bounds — see the Iron Law and the user's global rules.
"I found a broken agent, I'll fix its prompt now"	Out of scope. This skill reports and recommends; the fix is a separate, tracked change.

Red Flags — STOP

• Quoting any token number that did not come out of the script's JSON.
• Converting token counts into a cost or dollar figure — report raw counts only.
• Reading any file under ~/.claude other than the session transcript and its subagent logs — and never any credential or token file.
• Editing code, baselines, or pipeline config "while you're in there". Report only.
• Grading an axis with adjectives instead of the cited metric.

Cross-references

• Helper script: scripts/postmortem.py — the deterministic aggregator. All numbers originate here.
• Hand-off target: the issue skill, when a finding is a trackable defect worth filing.
• Report destination (optional): the project's post-mortem directory, if its CLAUDE.md project facts name one.
• Data-source note: this skill reads only the current session's own transcript and subagent logs. It does not crawl other projects or other sessions (single-session by design).