Pre-Mortem Skill

Pre-Mortem Skill

Quick Ref: Checklist generation -> Tooling -> Agent verification. Output: .agents/​pre-mortems/​*.md

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Architecture: Generate explicit checklist from failure-taxonomy.md BEFORE reading spec. Tools verify what's verifiable. Agents check what requires judgment. Every finding must have location (line number) and specific fix.

Execution Steps

Given /​pre-mortem <spec-or-plan>:

Step 1: Load the Spec/​Plan

If a path is provided, read it:

Tool: Read
Parameters:
  file_path: <provided path>

If no path, check for recent plans:

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

Step 1a: Search for Prior Failure Learnings (if ao available)

Before generating the checklist, search for relevant past failures:

# Search for prior failure patterns related to this topic
ao search "failure <topic>" 2>/​dev/​null || echo "ao not available, skipping failure pattern search"

# Also search for incidents and anti-patterns
ao search "incident <topic>" 2>/​dev/​null
ao anti-patterns 2>/​dev/​null | grep -i "<topic>" || true

Review ao search results: If ao returns relevant learnings, incorporate them:

• Prior incidents: Add checks for conditions that caused past failures
• Known anti-patterns: Add specific checklist items to verify they're avoided
• Lessons learned: Use these to generate additional verification questions

Note: This search runs BEFORE generating the checklist so prior knowledge can inform what to check.

Step 2: Generate Explicit Checklist BEFORE Reading

Load the failure taxonomy FIRST:

Tool: Read
Parameters:
  file_path: skills/​pre-mortem/​references/​failure-taxonomy.md

For each category in the taxonomy, generate specific questions:

The checklist above covers 7 essential items. For comprehensive validation, use all 10 categories from references/​failure-taxonomy.md.

Build the checklist BEFORE reading the spec. This prevents pattern-matching bias.

Step 3: Run Mechanical Cross-Reference Check

Before dispatching agents, run automated cross-reference:

./​scripts/​spec-cross-reference.sh <spec-file> | tee .agents/​pre-mortems/​cross-ref.md

This catches mechanically:

• File paths that don't exist
• Function/​type references that aren't defined
• Broken markdown links

Include output in pre-mortem report under "## Cross-Reference Verification"

Step 3a: Run Available Tooling

If the spec references code that exists:

# If code exists, run linting
./​scripts/​toolchain-validate.sh --quick 2>&1 | head -30

If spec is for new code: Skip to Step 4.

Step 4: Dispatch Verification Agents (with Checklist)

Agents VERIFY checklist items, not "simulate failures".

Launch 3 agents in parallel:

Tool: Task (ALL 3 IN PARALLEL)
Parameters:
  subagent_type: "agentops:gap-identifier"
  model: "haiku"
  description: "Verify spec completeness against checklist"
  prompt: |
    Spec file: <spec content>

    Checklist to verify (from failure-taxonomy.md):

    For EACH item, read the spec and answer:
    | Checklist Item | Present? | Location (line) | Complete? |
    |----------------|----------|-----------------|-----------|
    | API schema defined | yes/​no | line N | yes/​partial/​no |
    | Timeouts specified | yes/​no | line N | yes/​partial/​no |
    | Error states listed | yes/​no | line N | yes/​partial/​no |
    | Rollback procedure | yes/​no | line N | yes/​partial/​no |
    | Dependencies listed | yes/​no | line N | yes/​partial/​no |
    | State transitions | yes/​no | line N | yes/​partial/​no |
    | Confirmation for destructive ops | yes/​no | line N | yes/​partial/​no |

    For items marked "no" or "partial": flag as GAP with specific fix.

Tool: Task
Parameters:
  subagent_type: "agentops:assumption-challenger"
  model: "haiku"
  description: "Find implicit assumptions"
  prompt: |
    Spec file: <spec content>

    Find statements that assume something without stating it:
    - "The user will..." -> What if they don't?
    - "The API returns..." -> What if it errors?
    - "This runs after..." -> What if order changes?

    For each assumption:
    | Location (line) | Assumption | What If Wrong? | Specific Clarification Needed |
    |-----------------|------------|----------------|-------------------------------|

    Every finding MUST have a line number and specific fix.

Tool: Task
Parameters:
  subagent_type: "agentops:edge-case-hunter"
  model: "haiku"
  description: "Find boundary conditions"
  prompt: |
    Spec file: <spec content>

    For each input/​parameter in the spec:
    | Location (line) | Input | Type | Min/​Max Stated? | Empty Handling? | Invalid Handling? |
    |-----------------|-------|------|-----------------|-----------------|-------------------|

    Flag any inputs without explicit boundary handling.
    Every finding MUST have a line number and specific fix.

Timeout: 2 minutes per agent.

Step 5: Categorize Findings

Combine agent outputs and categorize:

Every finding must have:

1. Location (line number in spec)
2. Description (what's missing or unclear)
3. Specific fix (exact text to add/​change)

Apply Enhancement Patterns

For each finding, identify the applicable pattern from references/​enhancement-patterns.md:

Step 6: Write Pre-Mortem Report

Write to: .agents/​pre-mortems/​YYYY-MM-DD-<topic>.md

# Pre-Mortem: <Topic>

**Date:** YYYY-MM-DD
**Spec:** <path to spec/​plan>

## Checklist Verification

| Category | Item | Present? | Location | Complete? |
|----------|------|----------|----------|-----------|
| Interface | API schema | yes/​no | line N | yes/​no |
| Timing | Timeouts | yes/​no | line N | yes/​no |
| Error | Error states | yes/​no | line N | yes/​no |
| Safety | Confirmation | yes/​no | line N | yes/​no |
| Rollback | Rollback procedure | yes/​no | line N | yes/​no |
| Deps | Dependencies listed | yes/​no | line N | yes/​no |
| State | State transitions | yes/​no | line N | yes/​no |

## Findings

### CRITICAL (Must Fix Before Implementation)
1. **<Issue>**: <Description>
   - **Location:** line N
   - **Why Critical:** <explanation>
   - **Specific Fix:** <exact text to add to spec>

### HIGH (Should Clarify)
1. **<Issue>**: <Description>
   - **Location:** line N
   - **Assumption Made:** <what's assumed>
   - **Specific Clarification:** <exact question to answer>

### MEDIUM
- **<Issue>** (line N): <issue and specific fix>

## Implicit Assumptions Found
| Location | Assumption | Risk | Clarification Needed |
|----------|------------|------|---------------------|

## Edge Cases Without Handling
| Location | Input | Boundary Missing | Suggested Handling |
|----------|-------|-----------------|-------------------|

## Verdict

[ ] READY - All checklist items present, no CRITICAL gaps
[ ] NEEDS WORK - <count> CRITICAL gaps must be addressed

Step 7: Request Human Approval (Gate 3)

Gate Criteria:

• READY: 0 CRITICAL gaps, <=2 HIGH gaps
• NEEDS WORK: 1+ CRITICAL or >2 HIGH gaps

Tool: AskUserQuestion
Parameters:
  questions:
    - question: "Pre-mortem found <N> gaps. Proceed to implementation?"
      header: "Gate 3"
      options:
        - label: "Proceed"
          description: "Gaps acceptable, start implementation"
        - label: "Fix Spec"
          description: "Address gaps before implementing"
        - label: "More Research"
          description: "Need more information"
      multiSelect: false

Step 8: Report to User

Tell the user:

1. Checklist verification results (table)
2. Number of gaps by severity
3. Top 3 items that need attention (with line numbers)
4. Location of pre-mortem report
5. Gate 3 decision

Key Differences from Previous Version