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
/pre-mortem path/to/PLAN.md
/pre-mortem --deep path/to/SPEC.md
/pre-mortem --mixed path/to/PLAN.md
/pre-mortem --preset=architecture path/to/PLAN.md
/pre-mortem --explorers=3 path/to/SPEC.md
/pre-mortem --debate path/to/PLAN.md
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:
idpatterndetection_questionchecklist_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:
ao metrics cite "<finding-path>" --type applied 2>/dev/null || true
ao metrics cite "<finding-path>" --type retrieved 2>/dev/null || true
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
fi
When PRODUCT.md exists in the project root AND the user did NOT pass an explicit --preset override:
- Read
PRODUCT.md content and include in the council packet via context.files
- In
--quick mode, keep the review inline and require the reviewer to assess user-value, adoption-barriers, and competitive-position directly from PRODUCT.md.
- 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.
- 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
