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

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 --explorers = 2 epic-123

deep investigation before judging

/post-mortem --debate epic-123

two-round adversarial review

/post-mortem --skip-checkpoint-policy epic-123

skip ratchet chain validation

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-.md

type : learning source : post - mortem - quick date : YYYY - MM - DD

Learning:

**

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: Saved to: .agents/learnings/YYYY-MM-DD-quick-.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" ) 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:

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 2: Load the Original Plan/Spec Before invoking council, load the original plan for comparison: If epic/issue ID provided: bd show to get the spec/description Search for plan doc: ls .agents/plans/ | grep 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" : "" } } 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:

Read the plan from

.agents/plans/

(most recent)

Compare planned issues against closed issues (

bd children

)

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 or closes before its proving commit exists, emit a proof artifact with

bash skills/post-mortem/scripts/write-evidence-only-closure.sh

and cite the durable tracked copy at

.agents/releases/evidence-only-closures/.json

in the council packet. The writer also emits a local council copy at

.agents/council/evidence-only-closures/.json

. The packet must record the selected

evidence_mode

plus repo-state detail that distinguishes staged files from broader worktree state so active-session audits stay mechanically replayable.

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

Run

/council

with the

retrospective

preset and always 3 judges:

/council --deep --preset=retrospective validate

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. 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 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= — 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) Phase 2: Extract Learnings Inline extraction of learnings from the completed work (formerly delegated to the retro skill). Step EX.1: Gather Context

Recent commits

git log --oneline -20 --since = "7 days ago"

Epic children (if epic ID provided)

bd children < epic-id

2

/dev/null | head -20

Recent plans and research

ls

-lt

.agents/plans/ .agents/research/

2

>

/dev/null

|

head

-10

Read relevant artifacts: research documents, plan documents, commit messages, code changes. Use the Read tool and git commands to understand what was done.

If retrospecting an epic:

Run the closure integrity quick-check from

references/context-gathering.md

(Phantom Bead Detection + Multi-Wave Regression Scan). Include any warnings in findings.

Step EX.2: Classify Learnings

Ask these questions:

What went well?

What approaches worked?

What was faster than expected?

What should we do again?

What went wrong?

What failed?

What took longer than expected?

What would we do differently?

What did we discover?

New patterns found

Codebase quirks learned

Tool tips discovered

Debugging insights

For each learning, capture:

ID

L1, L2, L3...

Category

debugging, architecture, process, testing, security

What

The specific insight

Why it matters

Impact on future work

Confidence

high, medium, low Step EX.3: Write Learnings Write to: .agents/learnings/YYYY-MM-DD-.md

id : learning - YYYY - MM - DD - <slug

type : learning date : YYYY - MM - DD category : <category

confidence : <high | medium | low

Learning:

What We Learned <1-2 sentences describing the insight>

Why It Matters <1 sentence on impact/value>

Source < What work this came from

Learning:

**

ID

**

L2 ... Step EX.4: Classify Learning Scope For each learning extracted in Step EX.3, classify: Question: "Does this learning reference specific files, packages, or architecture in THIS repo? Or is it a transferable pattern that helps any project?" Repo-specific -> Write to .agents/learnings/ (existing behavior from Step EX.3). Use git rev-parse --show-toplevel to resolve repo root — never write relative to cwd. Cross-cutting/transferable -> Rewrite to remove repo-specific context (file paths, function names, package names), then: Write abstracted version to ~/.agents/learnings/YYYY-MM-DD-.md (NOT local — one copy only) Run abstraction lint check: file = "" grep -iEn '(internal/|cmd/|.go:|/pkg/|/src/|AGENTS.md|CLAUDE.md)' " $file " 2

/dev/null grep -En '[A-Z][a-z]+[A-Z][a-z]+.(go|py|ts|rs)' " $file " 2

/dev/null grep -En './[a-z]+/' " $file " 2

/dev/null If matches: WARN user with matched lines, ask to proceed or revise. Never block the write. Note: Each learning goes to ONE location (local or global). No promoted_to needed — there's no local copy to mark when writing directly to global. Example abstraction: Local: "Athena's validate package needs O_CREATE|O_EXCL for atomic claims because Zeus spawns concurrent workers" Global: "Use O_CREATE|O_EXCL for atomic file creation when multiple processes may race on the same path" Step EX.5: Write Structured Findings to Registry 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 This registry is the v1 advisory prevention surface. It complements learnings and next-work; it does not replace them. Step EX.6: Compile Constraint Templates (Deferred Follow-On) Constraint compilation remains a follow-on surface. Do not present draft templates as active runtime enforcement in the v1 registry-first slice. If you are explicitly operating in a later compiler-enabled slice, for each extracted learning scoring >= 4/5 on actionability AND tagged "constraint" or "anti-pattern", run bash hooks/constraint-compiler.sh to generate a constraint template.

Compile high-scoring constraint/anti-pattern learnings into enforcement templates

for f in .agents/learnings/YYYY-MM-DD-*.md ; do [ -f " $f " ] || continue bash hooks/constraint-compiler.sh " $f " 2

/dev/null || true done This produces draft constraint templates in .agents/constraints/ that can later be activated via ao constraint activate , but that activation path is not part of the v1 registry-first contract. Phase 3: Process Backlog Score, deduplicate, and flag stale learnings across the full backlog. This phase runs on ALL learnings, not just those extracted in Phase 2. Read references/backlog-processing.md for detailed scoring formulas, deduplication logic, and staleness criteria. Step BP.1: Load Last-Processed Marker MARKER = ".agents/ao/last-processed" mkdir -p .agents/ao if [ ! -f " $MARKER " ] ; then date -v-30d +%Y-%m-%dT%H:%M:%S 2

/dev/null || date -d "30 days ago" --iso-8601 = seconds

" $MARKER " fi LAST_PROCESSED = $( cat " $MARKER " ) Step BP.2: Scan Unprocessed Learnings find .agents/learnings/ -name ".md" -newer " $MARKER " -not -path "/archive/*" -type f | sort If zero files found: report "Backlog empty — no unprocessed learnings" and skip to Phase 4. Step BP.3: Deduplicate For each pair of unprocessed learnings: Extract

Learning:

title Normalize: lowercase, strip punctuation, collapse whitespace If two normalized titles share >= 80% word overlap, merge: Keep the file with highest confidence (high > medium > low); if tied, keep most recent Archive the duplicate with a merged_into: pointer Step BP.4: Score Each Learning Compute composite score for each learning: Factor Values Points Confidence high=3, medium=2, low=1 1-3 Citations default=1, +1 per cite in .agents/ao/citations.jsonl 1+ Recency <7d=3, <30d=2, else=1 1-3 Score = confidence + citations + recency Step BP.5: Flag Stale Learnings that are >30 days old AND have zero citations are flagged for retirement in Phase 5.

Flag but do not archive yet — Phase 5 handles retirement

if [ " $DAYS_OLD " -gt 30 ] && [ " $CITE_COUNT " -eq 0 ] ; then echo "STALE: $LEARNING_FILE ( ${DAYS_OLD} d old, 0 citations)" fi Step BP.6: Report Phase 3 (Process Backlog) Summary: - N learnings scanned - N duplicates merged - N scored (range: X-Y) - N flagged stale Phase 4: Activate Promote high-value learnings and feed downstream systems. Read references/activation-policy.md for detailed promotion thresholds and procedures. If --skip-activate is set: Skip this phase entirely. Report "Phase 4 skipped (--skip-activate)." Step ACT.1: Promote to MEMORY.md Learnings with score >= 6 are promoted: Read the learning file Extract title and core insight Check MEMORY.md for duplicate entries (grep for key phrases) If no duplicate: append to

Key Lessons

in MEMORY.md

Key Lessons

**