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

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 (knowledge search, product context) unless --deep, --mixed, --debate, or --explorers is set. These pre-processing steps are for multi-judge council packets only.

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. Only run this step for --deep, --mixed, or --debate.

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

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:

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

Add to each judge's prompt when test pyramid check is active:

TEST PYRAMID CHECK: Review the plan's test coverage against the L0-L7 pyramid.
For each issue, verify:
1. Are the right test levels specified? (L0 for boundaries, L1 for behavior, L2 for integration)
2. Are there gaps where tests should exist but aren't planned?
3. Are any agent-autonomous levels (L0-L3) missing from code-change issues?
Report test pyramid findings in a "Test Coverage Gaps" section.

Auto-triggered when any issue in the plan modifies source code files (.go, .py, .ts, .rs, .js).

Step 3: Interpret Council Verdict

Step 4: Write Pre-Mortem Report

Write to: .agents/council/YYYY-MM-DD-pre-mortem-<topic>.md

---
id: pre-mortem-YYYY-MM-DD-<topic-slug>
type: pre-mortem
date: YYYY-MM-DD
source: "[[.agents/plans/YYYY-MM-DD-<plan-slug>]]"
prediction_ids:
  - pm-YYYYMMDD-001
  - pm-YYYYMMDD-002
---

# Pre-Mortem: <Topic>

## Council Verdict: PASS / WARN / FAIL

| ID | Judge | Finding | Severity | Prediction |
|----|-------|---------|----------|------------|
| pm-YYYYMMDD-001 | Missing-Requirements | ... | significant | <what will go wrong> |
| pm-YYYYMMDD-002 | Feasibility | ... | significant | <what will go wrong> |
| pm-YYYYMMDD-003 | Scope | ... | moderate | <what will go wrong> |

## Shared Findings
- ...

## Known Risks Applied
- `<finding-id>` — `<why it matched this plan>`

## Concerns Raised
- ...

## Recommendation
<council recommendation>

## Decision Gate

[ ] PROCEED - Council passed, ready to implement
[ ] ADDRESS - Fix concerns before implementing
[ ] RETHINK - Fundamental issues, needs redesign

Each finding gets a unique prediction ID (pm-YYYYMMDD-NNN) for downstream correlation. See references/prediction-tracking.md for the full tracking lifecycle.

Step 4.5: Persist Reusable Findings

If the verdict is WARN or FAIL, persist only the reusable plan/spec failures to .agents/findings/registry.jsonl.

Use the finding-registry contract:

• required fields: dedup_key, provenance, pattern, detection_question, checklist_item, applicable_when, 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

Do NOT write every comment. Persist only findings that should change future planning or review behavior.

After the registry update, if hooks/finding-compiler.sh exists, run:

bash hooks/finding-compiler.sh --quiet 2>/dev/null || true

This refreshes .agents/findings/*.md, .agents/planning-rules/*.md, .agents/pre-mortem-checks/*.md, and draft constraint metadata in the same session. session-end-maintenance.sh remains the idempotent backstop.

Step 5: Record Ratchet Progress

ao ratchet record pre-mortem 2>/dev/null || true

Step 6: Report to User

Tell the user:

1. Council verdict (PASS/WARN/FAIL)
2. Key concerns (if any)
3. Recommendation
4. Location of pre-mortem report

Integration with Workflow

/plan epic-123
    │
    ▼
/pre-mortem                    ← You are here
    │
    ├── PASS → /implement
    ├── WARN → Review, then /implement or fix
    └── FAIL → Fix plan, re-run /pre-mortem

Examples

Validate a Plan (Default — Inline)

User says: /pre-mortem .agents/plans/2026-02-05-auth-system.md

What happens:

1. Agent reads the auth system plan
2. Runs /council --quick validate <plan-path> (inline, no spawning)
3. Single-agent structured review finds missing error handling for token expiry
4. Council verdict: WARN
5. Output written to .agents/council/2026-02-13-pre-mortem-auth-system.md

Result: Fast pre-mortem report with actionable concerns. Use --deep for high-stakes plans needing multi-judge consensus.

Cross-Vendor Plan Validation

User says: /pre-mortem --mixed .agents/plans/2026-02-05-auth-system.md

What happens:

1. Agent runs mixed-vendor council (3 Claude + 3 Codex)
2. Cross-vendor perspectives catch platform-specific issues
3. Verdict: PASS with 2 warnings

Result: Higher confidence from cross-vendor validation before committing resources.

Auto-Find Recent Plan

User says: /pre-mortem

What happens:

1. Agent scans .agents/plans/ for most recent plan
2. Finds 2026-02-13-add-caching-layer.md
3. Runs inline council validation (no spawning, ~10% of full council cost)
4. Records ratchet progress

Result: Frictionless validation of most recent planning work.

Deep Review for High-Stakes Plan

User says: /pre-mortem --deep .agents/plans/2026-02-05-migration-plan.md

What happens:

1. Agent reads the migration plan
2. Searches knowledge flywheel for prior migration learnings
3. Checks PRODUCT.md for product context
4. Runs /council --deep --preset=plan-review validate <plan-path> (4 judges)
5. Council verdict with multi-perspective consensus

Result: Thorough multi-judge review for plans where the stakes justify spawning agents.

Troubleshooting

See Also

• skills/council/SKILL.md — Multi-model validation council
• skills/plan/SKILL.md — Create implementation plans
• skills/vibe/SKILL.md — Validate code after implementation

Reference Documents

• references/enhancement-patterns.md
• references/error-rescue-map-template.md
• references/failure-taxonomy.md
• references/simulation-prompts.md
• references/prediction-tracking.md
• references/spec-verification-checklist.md
• references/temporal-interrogation.md