systematic-debugging

Systematic Debugging

你遇到了一个问题。先别急着改代码——系统性调试是一种纪律，不是建议。

实测数据：系统性方法 15-30 分钟修复，随机修复方法 2-3 小时折腾。

Announce at start: "I'm using the systematic-debugging skill to investigate this issue methodically."

When to Use

• 测试失败且原因不明显
• 代码"应该工作"但就是不工作
• 问题时有时无（间歇性问题）
• 修了一个 bug 又冒出新 bug
• "我不知道为什么会这样"

The Iron Law

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│    未完成 Phase 1 之前，禁止提出任何修复方案                   │
│                                                             │
│    NO FIX PROPOSALS BEFORE PHASE 1 COMPLETION               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

这不可协商。这不是建议。你不能为自己绕过这条规则找理由。

4+1 Phase Framework

digraph debugging {
    rankdir=TB;
    node [shape=box];
    
    "Phase 0: Problem Intake" -> "Phase 1: Root Cause Investigation";
    "Phase 1: Root Cause Investigation" -> "Phase 2: Pattern Analysis";
    "Phase 2: Pattern Analysis" -> "Phase 3: Hypothesis Testing";
    "Phase 3: Hypothesis Testing" -> "Phase 4: Implementation with TDD";
    "Phase 4: Implementation with TDD" -> "Verified Fix" [style=dashed];
    
    "Phase 1: Root Cause Investigation" -> "Phase 0: Problem Intake" [label="信息不足" style=dotted];
    "Phase 3: Hypothesis Testing" -> "Phase 1: Root Cause Investigation" [label="假设错误" style=dotted];
}

---

Phase 0: Problem Intake（问题收集）

目的：收集足够信息，而非急于诊断

必须收集的信息

• 确切错误信息：完整的错误输出，不是"它报错了"
• 复现步骤：如何可靠地重现问题？
• 预期行为 vs 实际行为：应该发生什么？实际发生了什么？
• 最近更改：问题出现前改了什么？
• 环境信息：Node 版本、操作系统、依赖版本

Checklist

□ 我有完整的错误信息/堆栈跟踪
□ 我能可靠地重现问题
□ 我知道预期行为是什么
□ 我知道问题首次出现的时间/提交
□ 我了解相关的环境配置

Detection Commands

# 获取完整错误信息
npm test 2>&1 | tee error.log

# 查看最近更改
git log --oneline -10
git diff HEAD~3

# 环境信息
node -v && npm -v
cat package.json | jq '.dependencies'

⚠️ 如果无法收集完整信息，停在这里，先问问题获取更多信息。