premortem

事前验尸

通过系统性地审视计划、设计和实现，提前识别可能的失败模式。此方法基于 Gary Klein 的技巧，并由 Shreyas Doshi（Stripe）推广。

用法

/premortem              # Auto-detect context, choose depth
/premortem quick        # Force quick analysis (plans, PRs)
/premortem deep         # Force deep analysis (before implementation)
/premortem <file>       # Analyze specific plan or code

核心概念

“设想现在是 3 个月后，这个项目已经彻底失败了。它为什么会失败？”

风险类别（Shreyas 框架）

类别	符号	含义
猛虎	[TIGER]	若不处理，就会造成伤害的明确威胁
纸老虎	[PAPER]	看起来有威胁，但大概率无碍
房间里的大象	[ELEPHANT]	没人愿意谈论的问题

重要：标记前先验证

不要仅凭模式匹配就标记风险。 每个潜在的猛虎都必须经过验证。

误报问题

以下常见错误会导致误判为猛虎：

• 看到硬编码路径，却没有检查是否有 if exists(): 回退逻辑
• 发现缺少功能 X，却没有询问“X 是否在范围内？”
• 标记第 N 行的代码，却没有阅读其上下 N±20 行以了解上下文
• 假设错误情况未处理，却没有追踪代码

验证清单（必需）

标记任何猛虎之前，必须验证：

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

如果任何验证项的答案是“否”或“不确定”，就不要将其标记为猛虎。

必需的证据格式

每个猛虎都必须包含：

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"

如果无法用具体证据填写 mitigation_checked，它就不是经过验证的猛虎。

工作流

步骤 1：判断上下文和深度

# 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"}
        ]
    )

步骤 2：运行适当的清单

快速清单（计划、PR）

在心中逐项检查，并记下适用项：

核心问题：

1. 可能出错的最重要因素是什么？
2. 是否有可能失效的外部依赖？
3. 如果出现问题，能否回滚？
4. 测试是否遗漏了边界情况？
5. 是否有可能导致返工的需求不明确之处？

输出格式：

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

深入清单（实施前）

系统性地检查以下各类别：

技术风险：

• 可扩展性：能否应对当前负载的 10 倍／100 倍？
• 依赖项：是否明确外部服务及其回退方案？
• 数据：可用性、一致性和迁移是否明确？
• 延迟：能否满足 SLA 要求？
• 安全性：是否考虑了身份验证、注入攻击和 OWASP？
• 错误处理：是否覆盖了所有故障模式？

集成风险：

• 是否识别了破坏性变更？
• 是否定义了迁移路径？
• 是否有回滚策略？
• 是否需要功能标志？

流程风险：

• 需求是否清晰且完整？
• 是否收集了所有利益相关者的意见？
• 是否在跟踪技术债务？
• 是否了解维护负担？

测试风险：

• 是否识别了覆盖率缺口？
• 是否有集成测试计划？
• 是否需要负载测试？
• 是否定义了手动测试计划？

输出格式：

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>"]

步骤 3：通过 AskUserQuestion 呈现风险

必须执行： 呈现调查结果并要求用户作出决定。

# Build risk summary
risk_summary = format_risks(tigers, elephants)

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"
        }
    ]
)

步骤 4：处理用户回复

如果用户选择“接受风险并继续”

# Log acceptance for audit trail
print("Risks acknowledged. Proceeding with implementation.")
# Continue to next workflow step

如果用户选择“将缓解措施添加到计划中”

# User provides mitigation approach
# Update plan file with mitigations section
# Re-run quick premortem to verify mitigations address risks

如果用户选择“研究缓解方案”

# 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 to similar solutions
        - Patterns used
        - Libraries/utilities 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 to avoid
        """
    )

# Wait for research to complete
# Synthesize options
# Present via AskUserQuestion with 2-4 mitigation options

如果用户选择“讨论具体风险”

# Ask which risk to discuss
AskUserQuestion(
    question="Which risk would you like to discuss?",
    header="Risk",
    options=[format_risk_option(r) for r in all_risks[:4]]
)
# Then have conversation about that specific risk

步骤 5：更新计划（如添加了缓解措施）

如果用户添加了缓解措施，将其附加到计划中：

## Risk Mitigations (Pre-Mortem)

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

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

### Pre-Mortem Run:
- Date: {timestamp}
- Mode: {quick|deep}
- Tigers: {count}
- Elephants: {count}

集成点

在 create_plan / plan-agent 中

计划结构获批后、ExitPlanMode 之前：

# Run quick premortem
/premortem quick

# If HIGH risks found, block until addressed
# If only MEDIUM/LOW, inform and proceed

计划获批后、实施前

# Run deep premortem on full plan
/premortem deep thoughts/shared/plans/YYYY-MM-DD-feature.md

# Block until all HIGH tigers addressed

在 PR 审查工作流中

# Run quick premortem on diff scope
/premortem quick

# Inform of any risks found

严重程度阈值

严重程度	是否阻塞？	所需操作
HIGH	是	必须处理或明确接受
MEDIUM	否	告知用户，建议处理
LOW	否	提醒用户注意

示例会话

User: /premortem deep thoughts/shared/plans/2026-01-08-api-rate-limiting.md

Claude: Running deep pre-mortem on API rate limiting plan...

[Reviews plan against deep checklist]

Pre-mortem complete. Found 2 tigers, 1 elephant:

**TIGERS:**
1. [HIGH] No circuit breaker for external payment API
   - Category: dependency
   - If payment API is slow/down, requests will pile up

2. [HIGH] No rollback strategy defined
   - Category: integration
   - If rate limiting breaks auth flow, no quick fix path

**ELEPHANTS:**
1. [MEDIUM] Team hasn't used Redis before
   - We're introducing Redis for rate limit counters
   - Learning curve could slow implementation

**PAPER TIGERS:**
1. Database migration size - Only adds one index, <1s migration

[AskUserQuestion presented]

User: Research mitigation options

Claude: Researching mitigations...

[Spawns scout + oracle in parallel]

Found 3 options for circuit breaker:

1. **Use existing retry util** (Recommended)
   - Found at src/utils/retry.ts:45
   - Already handles exponential backoff
   - Just need to add circuit breaker state

2. **Add resilience4j-lite**
   - Popular library for this pattern
   - More features but new dependency

3. **Custom implementation**
   - Full control but more code to maintain

Which approach for the circuit breaker?

User: Option 1 - use existing retry util

Claude: Added to plan:

## Risk Mitigations (Pre-Mortem)

### Tigers Addressed:
1. **No circuit breaker** (HIGH)
   - Mitigation: Extend src/utils/retry.ts with circuit breaker state
   - Added to Phase 1

Shall I also address the rollback strategy tiger?

参考资料

• Shreyas Doshi 的事前复盘
• Gary Klein 的原始研究
• 项目事前复盘指南 - Mountain Goat Software