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 does not expose that hook surface, so Codex sessions should finish closeout with ao codex stop.
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 --process-only
/post-mortem --skip-activate
/post-mortem --deep recent
/post-mortem --mixed epic-123
/post-mortem --skip-checkpoint-policy epic-123
Codex Closeout
In Codex hookless mode, 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. |
--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
Given /post-mortem --quick "insight text":
Quick Step 1: Generate Slug
Create a slug from the content: first meaningful words, lowercase, hyphens, max 50 chars.
Quick Step 2: Write Learning Directly
Write to: .agents/learnings/YYYY-MM-DD-quick-<slug>.md
---
type: learning
source: post-mortem-quick
date: YYYY-MM-DD
maturity: provisional
utility: 0.5
---
# Learning: <Short Title>
**Category**: <auto-classify: debugging|architecture|process|testing|security>
**Confidence**: medium
## What We Learned
<user's insight text>
## Source
Quick capture via `/post-mortem --quick`
This skips the full pipeline — writes directly to learnings, no council or backlog processing.
Quick Step 3: Confirm
Learned: <one-line summary>
Saved to: .agents/learnings/YYYY-MM-DD-quick-<slug>.md
For deeper reflection, use `/post-mortem` without --quick.
Done. Return immediately after confirmation.
Execution Steps
Pre-Flight Checks
Before proceeding, verify:
- Git repo exists:
git rev-parse --git-dir 2>/dev/null — if not, error: "Not in a git repository"
- Work was done:
git log --oneline -1 2>/dev/null — if empty, error: "No commits found. Run /implement first."
- Epic context: If epic ID provided, verify it has closed children. If 0 closed children, error: "No completed work to review."
If --process-only: Skip Pre-Flight Checks through Step 3. Jump directly to Phase 3: Process Backlog.
Step 0.4: Load Reference Documents (MANDATORY)
Before Step 0.5 and Step 2.5, load required reference docs into context using the Read tool:
REQUIRED_REFS=(
"skills/post-mortem/references/checkpoint-policy.md"
"skills/post-mortem/references/metadata-verification.md"
"skills/post-mortem/references/closure-integrity-audit.md"
"skills/post-mortem/references/four-surface-closure.md"
)
For each reference file, use the Read tool to load its content and hold it in context for use in later steps. Do NOT just test file existence with [ -f ] -- actually read the content so it is available when Steps 0.5 and 2.5 need it.
If a reference file does not exist (Read returns an error), log a warning and add it as a checkpoint warning in the council context. Proceed only if the missing reference is intentionally deferred.
Step 0.5: Checkpoint-Policy Preflight (MANDATORY)
Read references/checkpoint-policy.md for the full checkpoint-policy preflight procedure. It validates the ratchet chain, checks artifact availability, and runs idempotency checks. BLOCK on prior FAIL verdicts; WARN on everything else.
Step 1: Identify Completed Work and Record Timing
Record the post-mortem start time for cycle-time tracking:
PM_START=$(date +%s)
If epic/issue ID provided: Use it directly.
If no ID: Find recently completed work:
bd list --status closed --since "7 days ago" 2>/dev/null | head -5
git log --oneline --since="7 days ago" | head -10
Step 1.5: RPI Session Metrics
Read .agents/rpi/rpi-state.json and extract session ID, phase, verdicts, and streak data. If absent or unparseable, skip silently. Prepend a tweetable summary to the report: > RPI streak: N consecutive days | Sessions: N | Last verdict: PASS/WARN/FAIL. See references/streak-tracking.md for extraction logic and fallback behavior.
Step 2: Load the Original Plan/Spec
Before invoking council, load the original plan for comparison:
- If epic/issue ID provided:
bd show <id> to get the spec/description
- Search for plan doc:
ls .agents/plans/ | grep <target-keyword>
- Check git log:
git log --oneline | head -10 to find the relevant bead reference
If a plan is found, include it in the council packet's context.spec field:
{
"spec": {
"source": "bead na-0042",
"content": "<the original plan/spec text>"
}
}
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.
Step 2.2: Load Implementation Summary
Check for a crank-generated phase-2 summary:
PHASE2_SUMMARY=$(ls -t .agents/rpi/phase-2-summary-*-crank.md 2>/dev/null | head -1)
if [ -n "$PHASE2_SUMMARY" ]; then
echo "Phase-2 summary found: $PHASE2_SUMMARY"
fi
If available, use the phase-2 summary to understand what was implemented, how many waves ran, and which files were modified.
Step 2.3: Reconcile Plan vs Delivered Scope
Compare the original plan scope against what was actually delivered:
- Read the plan from
.agents/plans/ (most recent)
- Compare planned issues against closed issues (
bd children <epic-id>)
- Note any scope additions, removals, or modifications
- Include scope delta in the post-mortem findings
Step 2.4: Closure Integrity Audit (MANDATORY)
Read references/closure-integrity-audit.md for the full procedure. Mechanically verifies:
- Evidence precedence per child — every closed child resolves on the strongest available evidence in this order:
commit, then staged, then worktree
- Phantom bead detection — flags children with generic titles ("task") or empty descriptions
- Orphaned children — beads in
bd list but not linked to parent in bd show
- Multi-wave regression detection — for crank epics, checks if a later wave removed code added by an earlier wave
- Stretch goal audit — verifies deferred stretch goals have documented rationale
Include results in the council packet as context.closure_integrity. WARN on 1-2 findings, FAIL on 3+.
If a closure is evidence-only, emit a proof artifact with bash skills/post-mortem/scripts/write-evidence-only-closure.sh and cite at .agents/releases/evidence-only-closures/<target-id>.json. Record evidence_mode plus repo-state detail for replayability. A valid durable packet is acceptable audit evidence even when the child intentionally has no scoped-file section.
Step 2.5: Pre-Council Metadata Verification (MANDATORY)
Read references/metadata-verification.md for the full verification procedure. Mechanically checks: plan vs actual files, file existence in commits, cross-references in docs, and ASCII diagram integrity. Failures are included in the council packet as context.metadata_failures.
Step 2.6: Pre-Council Deep Audit Sweep
Skip if --quick or --skip-sweep.
Before council runs, dispatch a deep audit sweep to systematically discover issues across all changed files. This uses the same protocol as /vibe --deep — see the deep audit protocol in the vibe skill (skills/vibe/) for the full specification.
In summary:
- Identify all files in scope (from epic commits or recent changes)
- Chunk files into batches of 3-5 by line count (<=100 lines -> batch of 5, 101-300 -> batch of 3, >300 -> solo)
- Dispatch up to 8 Explore agents in parallel, each with a mandatory 8-category checklist per file (resource leaks, string safety, dead code, hardcoded values, edge cases, concurrency, error handling, HTTP/web security)
- Merge all explorer findings into a sweep manifest at
.agents/council/sweep-manifest.md
- Include sweep manifest in council packet — judges shift to adjudication mode (confirm/reject/reclassify sweep findings + add cross-cutting findings)
Why: Post-mortem council judges exhibit satisfaction bias when reviewing monolithic file sets — they stop at ~10 findings regardless of actual issue count. Per-file explorers with category checklists find 3x more issues, and the sweep manifest gives judges structured input to adjudicate rather than discover from scratch.
Skip conditions:
--quick flag -> skip (fast inline path)--skip-sweep flag -> skip (old behavior: judges do pure discovery)- No source files in scope -> skip (nothing to audit)
Step 3: Council Validates the Work
Council Verdict:
Run /council with the retrospective preset and always 3 judges:
/council --deep --preset=retrospective validate <epic-or-recent>
Default (3 judges with retrospective perspectives):
plan-compliance: What was planned vs what was delivered? What's missing? What was added?tech-debt: What shortcuts were taken? What will bite us later? What needs cleanup?learnings: What patterns emerged? What should be extracted as reusable knowledge?
Post-mortem always uses 3 judges (--deep) because completed work deserves thorough review.
Four-Surface Closure: Validate all four surfaces -- Code, Documentation, Examples, and Proof. A PASS verdict requires all four surfaces addressed, not just code correctness. Read skills/post-mortem/references/four-surface-closure.md for the closure checklist and common gaps.
Timeout: Post-mortem inherits council timeout settings. If judges time out,
the council report will note partial results. Post-mortem treats a partial council
report the same as a full report — the verdict stands with available judges.
The plan/spec content is injected into the council packet context so the plan-compliance judge can compare planned vs delivered.
With --quick (inline, no spawning):
/council --quick validate <epic-or-recent>
Single-agent structured review. Fast wrap-up without spawning.
With debate mode:
/post-mortem --debate epic-123
Enables adversarial two-round review for post-implementation validation. Use for high-stakes shipped work where missed findings have production consequences. See /council docs for full --debate details.
Advanced options (passed through to council):
--mixed — Cross-vendor (Claude + Codex) with retrospective perspectives--preset=<name> — Override with different personas (e.g., --preset=ops for production readiness)--explorers=N — Each judge spawns N explorers to investigate the implementation deeply before judging--debate — Two-round adversarial review (judges critique each other's findings before final verdict)
Step 3.5: Prediction Accuracy (Pre-Mortem Correlation)
When a pre-mortem report exists for the current epic (ls -t .agents/council/*pre-mortem*.md), cross-reference its prediction IDs against actual vibe/implementation findings. Score each as HIT (prediction confirmed), MISS (did not materialize), or SURPRISE (unpredicted issue). Write a ## Prediction Accuracy table in the report. Skip silently if no pre-mortem exists. See re
