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: Verify Checklist Items

Verify checklist items systematically. Do not "simulate failures" - check for specific gaps.

4a. Verify Spec Completeness

For EACH checklist item from failure-taxonomy.md, read the spec and answer:

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

4b. Find Implicit Assumptions

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?

Record assumptions:

Every finding MUST have a line number and specific fix.

4c. Find Boundary Conditions

For each input/parameter in the spec:

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

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