pre-mortem

name	pre-mortem
description	Checklist-driven spec validation. Generates explicit checklists from failure-taxonomy.md, runs available tooling, then dispatches agents to verify checklist items. Triggers: "pre-mortem", "validate spec", "what could go wrong".

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:

Category	Checklist Item	Verification Method
Interface Mismatch	Does spec define API schema?	Search for schema: or interface
Timing	Does spec define timeouts?	Search for timeout:
Error Handling	Does spec define error states?	Search for error: or failure:
Safety	Does spec require confirmation for destructive ops?	Search for confirm
Integration	Does spec list dependencies?	Search for depends: or requires:
Rollback	Does spec define rollback procedure?	Search for rollback or revert
State	Does spec define state transitions?	Search for state: or transition

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:

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.

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:

Location (line)	Assumption	What If Wrong?	Specific Clarification Needed

Every finding MUST have a line number and specific fix.

4c. Find Boundary Conditions

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.

Step 5: Categorize Findings

Combine agent outputs and categorize:

Severity	Definition	Action
CRITICAL	Spec has fundamental gap (no rollback, no error handling)	Must fix before implementation
HIGH	Spec makes unstated assumptions	Should clarify
MEDIUM	Spec could be clearer	Worth noting
LOW	Minor improvements	Optional

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:

Gap Type	Enhancement Pattern
Missing schema	"Schema from Code" - Extract schema from actual code
Missing error handling	"Error Recovery Matrix" - Map all error types to actions
Missing timeouts	"Per-Tool Timeout Configuration" - Add per-operation timeouts
Missing safety info	"Mandatory Safety Display" - Add safety level classification
Missing progress feedback	"Progress Feedback Specification" - Add update frequency
Missing escalation	"Escalation Flow" - Define when/how to escalate
Missing audit trail	"Audit Trail Requirements" - Add logging requirements

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

Before	After
"Simulate failures" (vague)	Verify checklist items (specific)
4 failure experts	3 verification agents
Gestalt impression	Explicit checklist + location (line number)
No methodology	Uses failure-taxonomy.md
Findings without location	Every finding has line number and specific fix
Pattern matching	Mechanical verification