| name | post-mortem |
| description | Review completed work and learn. Use when: a task, PR arc, or session is finished and you want to extract learnings, or after ≥5 PRs (the scope checkpoint). |
| practices | ["dora-metrics","sre","lean-startup"] |
| hexagonal_role | domain |
| consumes | ["implement","validate","council"] |
| produces | ["result.json"] |
| context_rel | [{"kind":"shared-kernel","with":"standards"}] |
| skill_api_version | 1 |
| metadata | {"tier":"judgment","dependencies":["council","beads-br"]} |
| context | {"window":"fork","intent":{"mode":"task"},"sections":{"exclude":["HISTORY"]},"intel_scope":"full"} |
| output_contract | skills/council/schemas/verdict.json |
Post-Mortem Skill
Purpose: Wrap up completed work — validate it shipped correctly, extract learnings, process the knowledge backlog, activate high-value insights, and retire stale knowledge.
Runtime note: Hook-driven closeout is runtime-dependent. Claude/OpenCode can wire Phase 2-5 maintenance through lifecycle hooks. Codex CLI v0.115.0+ supports native hooks (same behavior). For older Codex versions without hook surfaces, finish closeout with ao codex stop.
Loop position
Move 7 (capture evidence + learning, then ratchet) of the operating loop. Two outputs per loop turn: evidence (test names, snapshot keys, council verdicts, citation events) recorded against the bead and .agents/flywheel/; learnings promoted only under the ratchet rules — noticed once stays in the handoff, repeats twice goes to .agents/learnings/, changes future behavior updates a SKILL.md or template, must-never-regress becomes a gate, core doctrine promotes into PRODUCT.md/GOALS.md/docs/cdlc.md. Most observations die at handoff. That is correct.
Route a promoted learning to the WEAKEST enforcement surface that actually
changes behavior — this is the ladder, by strength, not three copies of the
same note:
| Surface | Strength | Promote here when |
|---|
AGENTS.md/CLAUDE.md | always-on context | doctrine relevant to most turns in this repo |
| a SKILL.md | JIT, model-invoked | contextual judgment that fires on a trigger |
| a gate/hook | mechanical, un-skippable | must-never-regress; cannot be left to judgment |
Put it as high as needed and no higher: a hook for what an agent must not be
able to skip; a skill for what it should choose well; AGENTS.md for what it
should always know. A lesson that only needs to be known doesn't need a hook;
a lesson that must never regress is wasted as prose. If the existing
hook/gate layer already catches the failure (it fired, just late), the fix is
usually one rung weaker — teach a skill/AGENTS.md to run that gate earlier, not
add a redundant hook.
Measure the shipped change on real data, not just unit-green. A learning or
feature that is unit-correct but has zero observable effect on the real
corpus/workload is a STOP signal (stop investing in it), not a "do more"
signal. Cite the real-data measurement (counts before/after on the actual
corpus), not just "tests pass."
Six phases:
- Council — Did we implement it correctly?
- Extract — What did we learn?
- Process Backlog — Score, deduplicate, and flag stale learnings
- Activate — Promote high-value learnings to MEMORY.md and constraints
- Retire — Archive stale and superseded learnings
- Harvest — Surface next work for the flywheel
Quick Start
/post-mortem
/post-mortem epic-123
/post-mortem --quick "insight"
/post-mortem --scope=pr <num>
/post-mortem --process-only
/post-mortem --skip-activate
/post-mortem --deep recent
/post-mortem --mixed epic-123
/post-mortem --skip-checkpoint-policy epic-123
Codex Closeout
Codex CLI v0.115.0+ has native hooks and handles closeout automatically (no extra steps needed). For older Codex versions (hookless fallback), run these after the post-mortem workflow writes learnings and next work:
ao codex stop
ao codex status
ao codex stop uses the latest transcript or history fallback to queue/persist learnings and run close-loop maintenance without runtime hooks.
Flags
| Flag | Default | Description |
|---|
--quick "text" | off | Quick-capture a single learning directly to .agents/learnings/ without running a full post-mortem. Formerly handled by /retro --quick. |
--scope=pr [num] | off | Read a merged/rejected PR outcome as the wrap-up signal instead of a closed bead/epic — mine reviewer feedback into a PR learning. Absorbed the former pr-retro skill. See references/pr-scope.md. |
--process-only | off | Skip council and extraction (Phase 1-2). Run Phase 3-5 on the existing backlog only. |
--skip-activate | off | Extract and process learnings but do not write to MEMORY.md (skip Phase 4 promotions). |
--deep | off | 3 judges (default for post-mortem) |
--mixed | off | Cross-vendor (Claude + Codex) judges |
--explorers=N | off | Each judge spawns N explorers before judging |
--debate | off | Two-round adversarial review |
--skip-checkpoint-policy | off | Skip ratchet chain validation |
--skip-sweep | off | Skip pre-council deep audit sweep |
Quick Mode
Read references/quick-mode.md when you need the --quick flag procedure (slug generation, direct learning write, confirmation).
PR-Outcome Scope (--scope=pr)
Read references/pr-scope.md when invoked with --scope=pr. It swaps the bead/epic wrap-up signal for a PR's merge/reject/changes-requested outcome: discover the PR, analyze the outcome, mine reviewer feedback via gh, extract success/failure patterns, and write a dated PR learning to .agents/learnings/. After the PR learning lands, the standard maintenance phases (process → activate → retire → harvest) run as usual. The trigger phrases "PR retro", "learn from this PR", and the legacy pr-retro command all route here.
Execution Steps
Read references/execution-steps.md when you need the full Phase 1 procedure: pre-flight checks, reference loading (Step 0.4), checkpoint-policy preflight (0.5), plan/spec loading (Steps 1-2.3), closure integrity audit (2.4), metadata verification (2.5), deep audit sweep (2.6), council invocation (Step 3), and prediction accuracy (3.5).
Step 2.1: Load Compiled Prevention Context
Before council and retro synthesis, load compiled prevention outputs when they exist:
.agents/planning-rules/*.md.agents/pre-mortem-checks/*.md
Use these compiled artifacts first, then fall back to .agents/findings/registry.jsonl only when compiled outputs are missing or incomplete. Carry matched finding IDs into the retro as Applied findings / Known risks applied context so post-mortem can judge whether the flywheel actually prevented rediscovery.
Phase 2: Extract Learnings
Read references/phase-2-extract.md when you need the inline learning extraction procedure: gather context (EX.1), classify (EX.2), write learnings (EX.3), test pyramid gap analysis (EX.3.5), scope classification (EX.4), findings registry (EX.5-6).
Before backlog processing, normalize reusable council findings into .agents/findings/registry.jsonl.
Use the tracked contract in docs/contracts/finding-registry.md:
- persist only reusable findings that should change future planning or review behavior
- require
dedup_key, provenance, pattern, detection_question, checklist_item, applicable_when, and confidence
applicable_when must use the controlled vocabulary from the contract- append or merge by
dedup_key
- use the contract's temp-file-plus-rename atomic write rule
After the registry mutation, refresh compiled outputs immediately so the same session can benefit from the updated prevention set.
If hooks/finding-compiler.sh exists, run:
bash hooks/finding-compiler.sh --quiet 2>/dev/null || true
Step ACT.3: Feed Next-Work
Actionable improvements identified during processing -> append one schema v1.4
batch entry to .agents/rpi/next-work.jsonl using the tracked contract in
../../docs/contracts/next-work.schema.md
and the write procedure in
references/harvest-next-work.md.
Follow the claim/finalize lifecycle documented in references/harvest-next-work.md.
The machine-checkable typed contract is the committed JSON Schema pair
../../schemas/next-work-batch.v1.schema.json
(one JSONL line = one batch entry) and
../../schemas/next-work-item.v1.schema.json
(each items[] element). Validate written rows with
../../scripts/validate-next-work.sh
(--strict to reject malformed output naming the offending field; advisory by
default). The inline bash in references/harvest-next-work.md remains a
dependency-free fallback when the script is unavailable.
mkdir -p .agents/rpi
ENTRY_TIMESTAMP="$(date -Iseconds)"
SOURCE_EPIC="${EPIC_ID:-recent}"
VALID_ITEMS_JSON="${VALID_ITEMS_JSON:-[]}"
printf '%s\n' "$(jq -cn \
--arg source_epic "$SOURCE_EPIC" \
--arg timestamp "$ENTRY_TIMESTAMP" \
--argjson items "$VALID_ITEMS_JSON" \
'{
source_epic: $source_epic,
timestamp: $timestamp,
items: $items,
consumed: false,
claim_status: "available",
claimed_by: null,
claimed_at: null,
consumed_by: null,
consumed_at: null
}'
)" >> .agents/rpi/next-work.jsonl
bash scripts/validate-next-work.sh .agents/rpi/next-work.jsonl
Step ACT.4: Update Marker
date -Iseconds > .agents/ao/last-processed
This must be the LAST action in Phase 4.
Phases 3-6 (Maintenance): Read references/maintenance-phases.md for backlog processing, activation, retirement, and harvesting phases. Load when --process-only flag is set or when running full post-mortem.
Reporting and Workflow
Read references/user-reporting.md when you need the Step 7 report template, mandatory next-/rpi suggestion format, workflow integration diagram, and example invocations.
Examples
Read references/user-reporting.md for full example invocations and what happens in each mode.
Troubleshooting
| Problem | Cause | Solution |
|---|
| Council times out | Epic too large or too many files changed | Split post-mortem into smaller reviews or increase timeout |
| No next-work items harvested | Council found no tech debt or improvements | Flywheel stable — write entry with empty items array to next-work.jsonl |
| Checkpoint-policy preflight blocks | Prior FAIL verdict in ratchet chain without fix | Resolve prior failure (fix + re-vibe) or skip checkpoint-policy via --skip-checkpoint-policy |
| Metadata verification fails | Plan vs actual files mismatch or missing cross-references | Include failures in council packet as context.metadata_failures — judges assess severity |
Compound-Engineering Retro (--compound)
A comparative-delta mode for projects that run ao goals measure repeatedly
across iterations of the same domain slice. Use when a slice has ≥2 iterations
in the verdict ledger and you want to know: what improved, what regressed, and
what the learning yield was since the last run.
Trigger: run this mode after any ao goals measure where the slice has a
prior iteration record in .agents/goals/verdict-ledger.json.
jq '[.records[] | select(.record_type=="iteration" and .directive_id=="d-<id>")] | length' \
.agents/goals/verdict-ledger.json
ao goals measure
ao goals history --goal <directive-id>
Then follow the step-by-step procedure in
references/compound-engineering-retro.md
(Steps CE.0–CE.5): extract N and N-1 records from the ledger, compute the
verdict and satisfaction delta, count learning yield, and write the delta as a
draft learning to .agents/learnings/YYYY-MM-DD-<slice>-iter-delta.md.
The output learning carries status: draft and the run IDs of both iterations;
human or Tier-3 synthesis promotes it to status: reviewed.
Closing the loop with re-steer. When the delta shows a directive failing
chronically, the verdict ledger also drives auto re-steer: ao goals steer recommend prints policy-driven directive mutations from the same ledger, and
ao goals steer apply writes the chosen mutation to GOALS.md — human-gated, via
the non-lossy patcher (policy auto_apply plus explicit confirmation; ADR-0006).
The compound retro names what regressed; re-steer proposes how the directive
should change. See the /goals skill.
See Also
skills/council/SKILL.md — Multi-model validation councilskills/validate/SKILL.md — Council validates code (/validate after coding)skills/pre-mortem/SKILL.md — Council validates plans (before implementation)pre-land-refuters — its council artifact (.agents/council/*-pre-land-*.md) is landing evidence this post-mortem consumes
Reference Documents
