Pre-Mortem Skill

Purpose: Is this plan/spec good enough to implement?

Mandatory for 3+ issue epics. Pre-mortem is enforced by hook when $crank is invoked on epics with 3+ child issues. 6/6 consecutive positive ROI. Bypass: --skip-pre-mortem flag or AGENTOPS_SKIP_PRE_MORTEM_GATE=1.

Run $council validate on a plan or spec to get multi-model judgment before committing to implementation.

Quick Start

$pre-mortem                                         # validates most recent plan (inline, no spawning)
$pre-mortem path/to/PLAN.md                         # validates specific plan (inline)
$pre-mortem --deep path/to/SPEC.md                  # 4 judges (thorough review, spawns agents)
$pre-mortem --mixed path/to/PLAN.md                 # cross-vendor (Claude + Codex)
$pre-mortem --preset=architecture path/to/PLAN.md   # architecture-focused review
$pre-mortem --explorers=3 path/to/SPEC.md           # deep investigation of plan
$pre-mortem --debate path/to/PLAN.md                # two-round adversarial review

Execution Steps

Step 0: Bead-Input Pre-Flight (Mandatory)

When the input to $pre-mortem is a bead ID ([a-z]{2,6}-[0-9a-z.]+) and the plan is full-complexity, older than 7 days, or inherited from a prior session, run ao beads verify <bead-id> as the first action.

if [[ "$INPUT" =~ ^[a-z]{2,6}-[0-9a-z.]+$ ]]; then
    ao beads verify "$INPUT" || true
fi

If verification reports STALE citations, stop in interactive mode and ask for scope re-validation before council review. In autonomous RPI mode, record the stale-scope evidence in the council packet and do not continue the go/no-go judgment against stale evidence.

This implements the shared stale-scope validation rule: inherited scope estimates must be re-validated against HEAD before acting on deferred beads, handoff docs, or prior-session plans.

Step 1: Find the Plan/Spec

If path provided: Use it directly.

If no path: Find most recent plan:

ls -lt .agents/plans/ 2>/dev/null | head -3
ls -lt .agents/specs/ 2>/dev/null | head -3

Use the most recent file. If nothing found, ask user.

Step 1.4: Retrieve Prior Learnings (Mandatory)

Before review, retrieve learnings relevant to this plan's domain:

if command -v ao &>/dev/null; then
    ao lookup --query "<plan goal or title>" --limit 5 2>/dev/null | head -30
fi

If learnings are returned, include them as known_context in the review packet. Cite any learning by filename when it influences a prediction. Skip silently if ao is unavailable or returns no results.

Step 1.4b: Load Compiled Prevention First (Mandatory)

Before quick or deep review, load compiled checks from .agents/pre-mortem-checks/*.md when they exist. This is separate from flywheel search and does NOT get skipped by --quick.

Use the tracked contracts in docs/contracts/finding-compiler.md and docs/contracts/finding-registry.md:

• prefer compiled pre-mortem checks first
• rank by severity, applicable_when overlap, language overlap, and literal plan-text overlap
• when the plan names files, rank changed-file overlap ahead of generic keyword matches
• cap at top 5 findings / check files
• if compiled checks are missing, incomplete, or fewer than the matched finding set, fall back to .agents/findings/registry.jsonl
• fail open:
  • missing compiled directory or registry -> skip silently
  • empty compiled directory or registry -> skip silently
  • malformed line -> warn and ignore that line
  • unreadable file -> warn once and continue without findings

Include matched entries in the council packet as known_risks with:

• id
• pattern
• detection_question
• checklist_item

Use the same ranked packet contract as $plan: compiled checks first, then active findings fallback, then matching high-severity next-work context when relevant. Avoid re-ranking with an unrelated heuristic inside pre-mortem; the point is consistent carry-forward, not a fresh retrieval policy per phase.

Record citations for applied knowledge:

After including matched entries as known_risks, record each citation so the flywheel feedback loop can track influence:

# Only use "applied" when the finding actually influenced the council packet.
# Use "retrieved" for items loaded but not referenced in the risk assessment.
ao metrics cite "<finding-path>" --type applied 2>/dev/null || true   # influenced risk assessment
ao metrics cite "<finding-path>" --type retrieved 2>/dev/null || true # loaded but not used

Section evidence: When lookup results include section_heading, matched_snippet, or match_confidence fields, prefer the matched section over the whole file — it pinpoints the relevant portion. Higher match_confidence (>0.7) means the section is a strong match; lower values (<0.4) are weaker signals. Use the matched_snippet as the primary context rather than reading the full file.

Step 1.5: Fast Path (--quick mode)

By default, pre-mortem runs inline (--quick) — single-agent structured review, no spawning. This catches real implementation issues at ~10% of full council cost (proven in ag-nsx: 3 actionable bugs found inline that would have caused runtime failures).

In --quick mode, skip Steps 1a and 1b as standalone pre-processing phases. If PRODUCT.md exists, Step 1b's product context is still loaded inline during the quick review. The mandatory ao lookup retrieval in Step 1.4 and compiled prevention load in Step 1.4b still run in quick mode. --deep, --mixed, --debate, and --explorers add the dedicated product perspective and wider council fan-out.

To escalate to full multi-judge council, use --deep (4 judges) or --mixed (cross-vendor).

Step 1.6: Scope Mode Selection

Before running council, determine the review posture. Three modes:

Auto-detection (when user doesn't specify):

• Greenfield feature → default EXPANSION
• Bug fix or hotfix → default HOLD SCOPE
• Refactor → default HOLD SCOPE
• Plan touching >15 files → suggest REDUCTION
• User says "go big" / "ambitious" → EXPANSION

Critical rule: Once mode is selected, COMMIT to it in the council packet. Do not silently drift. Include scope_mode: <expansion|hold|reduction> in the council packet context.

Mode-specific council instructions:

• EXPANSION: Add to judge prompt: "What would make this 10x more ambitious for 2x the effort? What's the platonic ideal? List 3 delight opportunities."
• HOLD SCOPE: Add to judge prompt: "The plan's scope is accepted. Your job: find every failure mode, test every edge case, ensure observability. Do not argue for less work."
• REDUCTION: Add to judge prompt: "Find the minimum viable version. Everything else is deferred. What can be a follow-up? Separate must-ship from nice-to-ship."

Step 1a: Search Knowledge Flywheel

Skip if --quick. Only run this step for --deep, --mixed, or --debate.

if command -v ao &>/dev/null; then
    ao search "plan validation lessons <goal>" 2>/dev/null | head -10
fi

If ao returns prior plan review findings, include them as context for the council packet. Skip silently if ao is unavailable or returns no results.

Step 1b: Check for Product Context

Skip if --quick as a separate pre-processing phase. In quick mode, the same product context is still loaded inline during review. In non-quick modes, add the dedicated product perspective.

if [ -f PRODUCT.md ]; then
  # PRODUCT.md exists — include product perspectives along