post-mortem

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 ensure-stop.

Six phases:

1. Council — Did we implement it correctly?
2. Extract — What did we learn?
3. Process Backlog — Score, deduplicate, and flag stale learnings
4. Activate — Promote high-value learnings to MEMORY.md and constraints
5. Retire — Archive stale and superseded learnings
6. Harvest — Surface next work for the flywheel

Quick Start

$post-mortem                    # wraps up recent work
$post-mortem epic-123           # wraps up specific epic
$post-mortem --quick "insight"  # quick-capture single learning (no council)
$post-mortem --process-only     # skip council+extraction, run Phase 3-5 on backlog
$post-mortem --skip-activate    # extract + process but don't write MEMORY.md
$post-mortem --deep recent      # thorough council review
$post-mortem --mixed epic-123   # cross-vendor (Claude + Codex)
$post-mortem --skip-checkpoint-policy epic-123  # skip ratchet chain validation

Codex Closeout

In Codex hookless mode, run these after the post-mortem workflow writes learnings and next work:

ao codex ensure-stop --auto-extract
ao codex status

ao codex ensure-stop is idempotent for the current Codex thread. It 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:

1. Git repo exists: git rev-parse --git-dir 2>/dev/null — if not, error: "Not in a git repository"
2. Work was done: git log --oneline -1 2>/dev/null — if empty, error: "No commits found. Run $implement first."
3. 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, read the required reference docs into context:

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, read 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:

# Check for closed beads
bd list --status closed --since "7 days ago" 2>/dev/null | head -5

# Or check recent git activity
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](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:

1. If epic/issue ID provided: bd show <id> to get the spec/description
2. Search for plan doc: ls .agents/plans/ | grep <target-keyword>
3. 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"
    # Read the summary with the Read tool for implementation context
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:

1. Read the plan from .agents/plans/ (most recent)
2. Compare planned issues against closed issues (bd children <epic-id>)
3. Note any scope additions, removals, or modifications
4. Include scope delta in the post-mortem findings

Step 2.4: Closure Integrity Audit (MANDATORY)

Read `references