premortem

name	premortem
description	Identify failure modes before they occur using structured risk analysis, with a cross-model adversarial pass (Codex, Grok, or both)
allowed-tools	["Read","Grep","Glob","Task","AskUserQuestion","TodoWrite","Bash"]

Pre-Mortem

Identify failure modes before they occur by systematically questioning plans, designs, and implementations. Based on Gary Klein's technique, popularized by Shreyas Doshi (Stripe). Augmented with a cross-model adversarial pass via OpenAI Codex — same training family = same blind spots, so Codex (different family) finds the tigers Claude misses.

Usage

/premortem                  # Auto-detect context, choose depth (includes Codex pass)
/premortem quick            # Force quick analysis (plans, PRs)
/premortem deep             # Force deep analysis (before implementation)
/premortem <file>           # Analyze specific plan or code
/premortem --no-codex       # Skip the cross-model pass entirely (Claude-only)
/premortem --grok           # Use Grok as the cross-model reviewer instead of Codex
/premortem --reviewers both # Run Codex AND Grok passes in parallel

Core Concept

"Imagine it's 3 months from now and this project has failed spectacularly. Why did it fail?"

Risk Categories (Shreyas Framework)

Category	Symbol	Meaning
Tiger	[TIGER]	Clear threat that will hurt us if not addressed
Paper Tiger	[PAPER]	Looks threatening but probably fine
Elephant	[ELEPHANT]	Thing nobody wants to talk about

CRITICAL: Verify Before Flagging

Do NOT flag risks based on pattern-matching alone. Every potential tiger MUST go through verification.

The False Positive Problem

Common mistakes that create false tigers:

• Seeing a hardcoded path without checking for if exists(): fallback
• Finding missing feature X without asking "is X in scope?"
• Flagging code at line N without reading lines N±20 for context
• Assuming error case isn't handled without tracing the code

Verification Checklist (REQUIRED)

Before flagging ANY tiger, verify:

potential_finding:
  what: "Hardcoded path at line 42"

verification:
  context_read: true    # Did I read ±20 lines around the finding?
  fallback_check: true  # Is there try/except, if exists(), or else branch?
  scope_check: true     # Is this even in scope for this code?
  dev_only_check: true  # Is this in __main__, tests/, or dev-only code?

result: tiger | paper_tiger | false_alarm

If ANY verification check is "no" or "unknown", DO NOT flag as tiger.

Required Evidence Format

Every tiger MUST include:

tiger:
  risk: "<description>"
  location: "file.py:42"
  severity: high|medium
  # REQUIRED - what mitigation was checked and NOT found:
  mitigation_checked: "No exists() check, no try/except, no fallback branch"

If you cannot fill in mitigation_checked with specific evidence, it's not a verified tiger.

Workflow

Step 1: Detect Context & Depth

# Auto-detect based on context
if in_plan_creation:
    depth = "quick"   # Localized scope
elif before_implementation:
    depth = "deep"    # Global scope
elif pr_review:
    depth = "quick"   # Localized scope
else:
    # Ask user
    AskUserQuestion(
        question="What depth of pre-mortem analysis?",
        header="Depth",
        options=[
            {"label": "Quick (2-3 min)", "description": "Plans, PRs, localized changes"},
            {"label": "Deep (5-10 min)", "description": "Before implementation, global scope"}
        ]
    )

Step 2: Run Appropriate Checklist

Quick Checklist (Plans, PRs)

Run through these mentally, note any that apply:

Core Questions:

1. What's the single biggest thing that could go wrong?
2. Any external dependencies that could fail?
3. Is rollback possible if this breaks?
4. Edge cases not covered in tests?
5. Unclear requirements that could cause rework?

Output Format:

premortem:
  mode: quick
  context: "<plan/PR being analyzed>"

  # Two-pass process: first gather potential risks, then verify each one
  potential_risks:  # Pass 1: Pattern-matching findings
    - "hardcoded path at line 42"
    - "missing error handling for X"

  # Pass 2: After verification
  tigers:
    - risk: "<description>"
      location: "file.py:42"
      severity: high|medium
      category: dependency|integration|requirements|testing
      mitigation_checked: "<what was NOT found>"  # REQUIRED

  elephants:
    - risk: "<unspoken concern>"
      severity: medium

  paper_tigers:
    - risk: "<looks scary but ok>"
      reason: "<why it's fine - what mitigation EXISTS>"
      location: "file.py:42-48"  # Show the mitigation location

  false_alarms:  # Findings that turned out to be nothing
    - finding: "<what was initially flagged>"
      reason: "<why it's not a risk>"

Deep Checklist (Before Implementation)

Work through each category systematically:

Technical Risks:

• Scalability: Works at 10x/100x current load?
• Dependencies: External services + fallbacks defined?
• Data: Availability, consistency, migrations clear?
• Latency: SLA requirements will be met?
• Security: Auth, injection, OWASP considered?
• Error handling: All failure modes covered?

Integration Risks:

• Breaking changes identified?
• Migration path defined?
• Rollback strategy exists?
• Feature flags needed?

Process Risks:

• Requirements clear and complete?
• All stakeholder input gathered?
• Tech debt being tracked?
• Maintenance burden understood?

Testing Risks:

• Coverage gaps identified?
• Integration test plan exists?
• Load testing needed?
• Manual testing plan defined?

Output Format:

premortem:
  mode: deep
  context: "<implementation being analyzed>"

  # Two-pass process
  potential_risks:  # Pass 1: Initial scan findings
    - "no circuit breaker for external API"
    - "hardcoded timeout value"

  # Pass 2: After verification (read context, check for mitigations)
  tigers:
    - risk: "<description>"
      location: "file.py:42"
      severity: high|medium
      category: scalability|dependency|data|security|integration|testing
      mitigation_checked: "<what mitigations were looked for and NOT found>"
      suggested_fix: "<how to address>"

  elephants:
    - risk: "<unspoken concern>"
      severity: medium|high
      suggested_fix: "<suggested approach>"

  paper_tigers:
    - risk: "<looks scary>"
      reason: "<why it's actually ok - cite the mitigation code>"
      location: "file.py:45-52"

  false_alarms:
    - finding: "<initial concern>"
      reason: "<why verification showed it's not a risk>"

  checklist_gaps:
    - category: "<which checklist section>"
      items_failed: ["<item1>", "<item2>"]

Step 2.5: Cross-Model Adversarial Pass (Codex / Grok / Both)

Same training family = same blind spots. After Claude's verified tigers/elephants/paper_tigers list is built, run an adversarial pass through one or more different-family reviewers to find risks Claude missed.

Reviewer selection. The post-ExitPlanMode hook (or the user directly) picks: Codex (default), Grok, Both, or Skip. --no-codex skips the Codex pass (back-compat); --grok uses Grok instead; --reviewers both runs both. When Both is selected, spawn the two adversary Tasks in parallel (single message, two tool calls).

Skip if the user chose Skip OR the target is a trivial doc-only change OR the relevant subscription quota is exhausted this session. See .claude/rules/codex-adversarial.md and .claude/rules/grok-worker-safety.md.

Reviewer agent type unavailable? Agents merged mid-session don't register until the next session start (hit 2026-07-11: grok-adversary absent from the Agent registry hours after merge). Do NOT silently downgrade to a Claude-family reviewer — that forfeits the cross-model value the user chose. Fallback: execute the adversary's own contract inline — read its .claude/agents/<name>.md, run the documented CLI invocation yourself (same read-only tool guard, same identity pin, same output paths), and parse findings from its clean-output file.

# Spawn the selected adversary agent(s) in plan mode pointed at the plan file.
# subagent_type: "codex-adversary" and/or "grok-adversary" — same prompt contract for both.
Task(
  subagent_type="codex-adversary",   # and/or "grok-adversary" (parallel when Both)
  prompt="""
  ## Mode
  plan

  ## Scope
  [absolute path to plan file being pre-mortemed]

  ## Focus
  Identify failure modes Claude missed. Claude already found:
  [list claude_tigers with one-line descriptions]

  Look for additional tigers (clear threats), elephants (unspoken concerns),
  or cases where Claude's paper_tigers were dismissed incorrectly.
  Different training family = different blind spots — that's the value.

  ## Codebase
  $CLAUDE_PROJECT_DIR
  """
)

Merge convention: findings get prefixed by source — [Codex] / [Grok] — and merged into the same tigers/elephants/paper_tigers lists. Findings flagged by TWO OR MORE models get confidence: cross-model-agreed — the high-confidence ones to act on first. Findings only one non-Claude model flags are that model's cross-model lift — track per model as the value signal of its pass.

# Merged output (Claude + Codex + Grok tigers, deduplicated by file:line + risk)
tigers:
  - risk: "<description>"
    location: "file.py:42"
    severity: high|medium
    sources: [claude, codex, grok]   # which model(s) found it
    mitigation_checked: "<what was NOT found>"

Step 3: Present Risks via AskUserQuestion

BLOCKING: Present findings and require user decision.

AskUserQuestion(
    question=f"""Pre-Mortem identified {len(tigers)} tigers, {len(elephants)} elephants:

{risk_summary}

How would you like to proceed?""",
    header="Risks",
    options=[
        {"label": "Accept risks and proceed", "description": "Acknowledged but not blocking"},
        {"label": "Add mitigations to plan (Recommended)", "description": "Update plan with risk mitigations before proceeding"},
        {"label": "Research mitigation options", "description": "I don't know how to mitigate - help me find solutions"},
        {"label": "Discuss specific risks", "description": "Talk through particular concerns"}
    ]
)

Step 4: Handle User Response

If "Accept risks and proceed"

Log acceptance and continue to next workflow step.

If "Add mitigations to plan"

Update plan file with mitigations section, then re-run quick premortem to verify mitigations address risks.

If "Research mitigation options"

Spawn parallel research for each HIGH severity tiger:

for tiger in high_severity_tigers:
    # Internal: How has codebase handled this before?
    Task(subagent_type="scout", prompt=f"""
        Find how this codebase has previously handled: {tiger.category}
        Specifically looking for patterns related to: {tiger.risk}
        Return: file:line references, patterns used, libraries available
    """)

    # External: What are best practices?
    Task(subagent_type="oracle", prompt=f"""
        Research best practices for: {tiger.risk}
        Context: {tiger.category} in a {tech_stack} codebase
        Return: recommended approaches (ranked), library options, common pitfalls
    """)

# Synthesize, present 2-4 mitigation options via AskUserQuestion

If "Discuss specific risks"

Ask which risk to discuss, then have conversation about that specific risk.

Step 5: Update Plan (if mitigations added)

Append to the plan file:

## Risk Mitigations (Pre-Mortem)

### Tigers Addressed:
1. **{risk}** (severity: {severity})
   - Mitigation: {mitigation}
   - Added to phase: {phase_number}

### Accepted Risks:
1. **{risk}** - Accepted because: {reason}

### Pre-Mortem Run:
- Date: {timestamp}
- Mode: {quick|deep}
- Cross-model pass: {codex|grok|both|skipped}
- Tigers: {total} (claude-only: {N}, codex-only: {N}, grok-only: {N}, agreed: {N}) | Elephants: {count}

Step 6: Telemetry

After the user response is handled, append one row per cross-model reviewer that ran — Codex rows to .claude/logs/codex-lift.jsonl, Grok rows to .claude/logs/grok-lift.jsonl (same schema, model field distinguishes):

mkdir -p "$CLAUDE_PROJECT_DIR/.claude/logs"
jq -nc \
  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg skill "premortem" \
  --arg scope "[plan path or scope]" \
  --arg model "codex" \
  --argjson claude_only <N> \
  --argjson codex_only <N> \
  --argjson both <N> \
  --arg via "direct" \
  '{ts:$ts, skill:$skill, scope:$scope, model:$model, claude_only:$claude_only, codex_only:$codex_only, both:$both, via:$via}' \
  >> "$CLAUDE_PROJECT_DIR/.claude/logs/codex-lift.jsonl"
# Grok pass ran too? Same shape with --arg model "grok", counts = grok_only in the codex_only
# position (field name kept for schema back-compat; `model` disambiguates), appended to grok-lift.jsonl.

The reviewer-only count is that model's cross-model lift — the value it added beyond what Claude found. Track over time per model to validate each pass is worth its quota.

Integration Points

Context	Mode	Behavior
During plan creation	quick	Run after plan structure approved, before ExitPlanMode
Before implementation	deep	Run on full plan file; block on HIGH risks
PR review	quick	Run on diff scope; inform of risks found

Severity Thresholds

Severity	Blocking?	Action Required
HIGH	Yes	Must address or explicitly accept
MEDIUM	No	Inform user, recommend addressing
LOW	No	Note for awareness

References

• references/example-session.md — Annotated walkthrough of a deep premortem session
• Pre-Mortems by Shreyas Doshi
• Gary Klein's Original Research
• Mountain Goat Software Guide