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

Mode	When to Use	Posture
SCOPE EXPANSION	Greenfield features, user says "go big"	Dream big. What's the 10-star version? Push scope UP.
HOLD SCOPE	Bug fixes, refactors, most plans	Maximum rigor within accepted scope. Make it bulletproof.
SCOPE REDUCTION	Plan touches >15 files, overbuilt	Strip to essentials. What's the minimum that ships value?

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 alongside plan-review
fi

When PRODUCT.md exists in the project root AND the user did NOT pass an explicit --preset override:

1. Read PRODUCT.md content and include in the council packet via context.files
2. In --quick mode, keep the review inline and require the reviewer to assess user-value, adoption-barriers, and competitive-position directly from PRODUCT.md.
3. In non-quick modes, add a single consolidated product perspective to the council invocation:

   /council --preset=plan-review --perspectives="product" validate <plan-path>
   

   This yields 3 judges total (2 plan-review + 1 product). The product judge covers user-value, adoption-barriers, and competitive-position in a single review.
4. With --deep: 5 judges (4 plan-review + 1 product).

When PRODUCT.md exists BUT the user passed an explicit --preset: skip product auto-include (user's explicit preset takes precedence).

When PRODUCT.md does not exist: proceed to Step 2 unchanged.

Tip: Create PRODUCT.md from docs/PRODUCT-TEMPLATE.md to enable product-aware plan validation.

Step 1.7: Load Council FAIL Patterns (Mandatory)

Read skills/pre-mortem/references/council-fail-patterns.md for the top 8 council FAIL patterns to check against.

These patterns are derived from 124 analyzed FAIL verdicts across 946 council sessions. They apply to both --quick and --deep modes.

Step 2: Run Council Validation

Default (inline, no spawning):

/council --quick validate <plan-path>

Single-agent structured review. Catches real implementation issues at ~10% of full council cost. Sufficient for most plans (proven across 6+ epics).

Default (2 judges with plan-review perspectives) applies when you intentionally run non-quick council mode.

With --deep (4 judges with plan-review perspectives):

/council --deep --preset=plan-review validate <plan-path>

Spawns 4 judges:

• missing-requirements: What's not in the spec that should be? What questions haven't been asked?
• feasibility: What's technically hard or impossible here? What will take 3x longer than estimated?
• scope: What's unnecessary? What's missing? Where will scope creep?
• spec-completeness: Are boundaries defined? Do conformance checks cover all acceptance criteria? Is the plan mechanically verifiable?

Use --deep for high-stakes plans (migrations, security, multi-service, 7+ issues).

With --mixed (cross-vendor):

/council --mixed --preset=plan-review validate <plan-path>

3 Claude + 3 Codex agents for cross-vendor plan validation with plan-review perspectives.

With explicit preset override:

/pre-mortem --preset=architecture path/to/PLAN.md

Explicit --preset overrides the automatic plan-review preset. Uses architecture-focused personas instead.

With explorers:

/council --deep --preset=plan-review --explorers=3 validate <plan-path>

Each judge spawns 3 explorers to investigate aspects of the plan's feasibility against the codebase. Useful for complex migration or refactoring plans.

With debate mode:

/pre-mortem --debate

Enables adversarial two-round review for plan validation. Use for high-stakes plans where multiple valid approaches exist. See /council docs for full --debate details.

Step 2.4: Temporal Interrogation (--deep and --temporal)

Included automatically with --deep. Also available via --temporal flag for quick reviews.

Walk through the plan's implementation timeline to surface time-dependent risks:

Phase	Questions
Hour 1: Setup	What blocks the first meaningful code change? Are dependencies available?
Hour 2: Core	Which files change in what order? Are there circular dependencies?
Hour 4: Integration	What fails when components connect? Which error paths are untested?
Hour 6+: Ship	What "should be quick" but historically isn't? What context is lost overnight?

Add to each judge's prompt when temporal interrogation is active:

TEMPORAL INTERROGATION: Walk through this plan's implementation timeline.
For each phase (Hour 1, 2, 4, 6+), identify:
1. What blocks progress at this point?
2. What fails silently at this point?
3. What compounds if not caught at this point?
Report temporal findings in a separate "Timeline Risks" section.

Auto-triggered (even without --deep) when the plan has 5+ files or 3+ sequential dependencies.

Retro history correlation: When .agents/retro/index.jsonl has 2+ entries, load the last 5 retros and check for recurring timeline-phase failures. Auto-escalate severity for phases that caused issues in prior retros.

Temporal findings appear in the report as a ## Timeline Risks table. See references/temporal-interrogation.md for the full framework.

Step 2.5: Error & Rescue Map (Mandatory for plans with external calls)

When the plan introduces methods, services, or codepaths that can fail, the council packet MUST include an Error & Rescue Map. If the plan omits one, generate it during review.

Include in the council packet as context.error_map:

Method/Codepath	What Can Go Wrong	Exception/Error	Rescued?	Rescue Action	User Sees
ServiceName#method	API timeout	TimeoutError	Y/N	Retry 2x, then raise	"Service unavailable"

Rules:

• Every external call (API, database, file I/O) must have at least one row
• rescue StandardError or bare except: is always a smell — name specific exceptions
• Every rescued error must: retry with backoff, degrade gracefully, OR re-raise with context
• For LLM/AI calls: map malformed response, empty response, hallucinated JSON, and refusal as separate failure modes
• Each GAP (unrescued error) is a finding with severity=significant

See references/error-rescue-map-template.md for the full template with worked examples.

Step 2.6: Council FAIL Pattern Check (Mandatory)

Council FAIL Pattern Check: Evaluate the plan against the top 8 council FAIL patterns (see references/council-fail-patterns.md): missing mechanical verification, self-assessment, context rot, propagation blindness, plan oscillation, dead infrastructure activation, missing rollback map, and four-surface closure gap. Each pattern violation is a finding with severity based on the calibration table in the reference.

Add to each judge's prompt:

COUNCIL FAIL PATTERN CHECK: Review this plan for the top 8 council FAIL patterns:
1. Missing mechanical verification — are all gates automated?
2. Self-assessment — is validation external to the implementer?
3. Context rot — are phase boundaries enforced with fresh sessions?
4. Propagation blindness — is the full change surface enumerated?
5. Plan oscillation — is direction validated before propagation?
6. Dead infrastructure activation — does the plan provision anything without activation tests?
7. Missing rollback map — does any production-state change lack a rollback procedure?
8. Four-surface closure — does the plan address Code + Docs + Examples + Proof for every feature?
Report FAIL pattern findings in a "FAIL Pattern Risks" section.

Auto-triggered for all plans (both --quick and --deep modes).

Step 2.7: Test Pyramid Coverage Check (Mandatory)

Validate that the plan includes appropriate test levels per the test pyramid standard (test-pyramid.md in the standards skill).

Check each issue in the plan:

Question	Expected	Finding if Missing
Does any issue touching external APIs include L0 (contract) tests?	Yes	severity=significant: "Missing contract tests for API boundary"
Does every feature/bug issue include L1 (unit) tests?	Yes	severity=significant: "Missing unit tests for feature/bug issue"
Do cross-module changes include L2 (integration) tests?	Yes	severity=moderate: "Missing integration tests for cross-module change"
Are L4+ levels deferred to human gate (not agent-planned)?	Yes	severity=low: "Agent planning L4+ tests — these require human-defined scenarios"

Add to each judge's pro