diagnosing-bugs

Diagnosing Bugs

面向棘手 bugs 的纪律。只有在明确说明理由时才跳过阶段。

探索 codebase 时，先读取 CONTEXT.md（如果存在），建立相关 modules 的清晰 mental model，并检查你将触碰区域的 ADRs。

Phase 1 - Build a feedback loop

这就是这个 skill 的核心。 其他所有内容都是机械步骤。如果你拥有一个针对该 bug 的 tight pass/fail signal，即它会在 _这个_ bug 上变红，你就能找到原因；bisection、hypothesis-testing 和 instrumentation 都只是消费这个 signal。没有它，盯着代码看多久都救不了你。

在这里投入不成比例的精力。要强硬、要有创造力、拒绝放弃。

Ways to construct one - try them in roughly this order

1. Failing test，放在能触达 bug 的 seam 上：unit、integration、e2e 都可以。
2. Curl / HTTP script，打到运行中的 dev server。
3. CLI invocation，使用 fixture input，并把 stdout 与 known-good snapshot diff。
4. Headless browser script（Playwright / Puppeteer），驱动 UI，并断言 DOM/console/network。
5. Replay a captured trace. 把真实 network request / payload / event log 保存到磁盘，并在隔离环境中 replay 到代码路径。
6. Throwaway harness. 启动系统的最小子集（一个 service、mocked deps），用一次 function call 触发 bug code path。
7. Property / fuzz loop. 如果 bug 是 "sometimes wrong output"，运行 1000 个 random inputs 并寻找 failure mode。
8. Bisection harness. 如果 bug 出现在两个已知状态之间（commit、dataset、version），自动化 "boot at state X, check, repeat"，这样可以 git bisect run。
9. Differential loop. 用同一 input 跑 old-version vs new-version（或两个 configs），然后 diff outputs。
10. HITL bash script. 最后手段。如果必须由人点击，就用 scripts/hitl-loop.template.sh 驱动 _人_，让 loop 仍保持结构化。捕获的输出反馈给你。

构建正确的 feedback loop，bug 就修好了 90%。

Tighten the loop

把 loop 当作产品。只要有了 _一个_ loop，就继续 tighten 它：

• 我能让它更快吗？（Cache setup、跳过无关 init、缩小 test scope。）
• 我能让 signal 更尖锐吗？（断言具体 symptom，而不是 "didn't crash"。）
• 我能让它更 deterministic 吗？（Pin time、seed RNG、isolate filesystem、freeze network。）

一个 30 秒且 flaky 的 loop 几乎不比没有 loop 好；一个 2 秒 deterministic loop 才是 tight 的调试超能力。

Non-deterministic bugs

目标不是 clean repro，而是 higher reproduction rate。循环触发 100x、parallelise、加 stress、缩小 timing windows、注入 sleeps。50%-flake bug 可以调试；1% 不行。持续提高复现率，直到它可调试。

When you genuinely cannot build a loop

停下来并明确说明。列出你尝试过什么。向用户请求：(a) 能复现的环境访问权限，(b) 捕获的 artifact（HAR file、log dump、core dump、带 timestamps 的 screen recording），或 (c) 添加临时 production instrumentation 的许可。不要 在没有 loop 时继续 hypothesise。

Completion criterion - a tight loop that goes red

Phase 1 完成条件：loop tight 且 red-capable。你能指出 一个 command（script path、test invocation、curl），并且你已经至少运行过一次（贴出 invocation 和 output），且它满足：

• [ ] Red-capable - 它驱动真实 bug code path，并断言 用户的 exact symptom，因此能在该 bug 上变红、修复后变绿。不是 "runs without erroring"，而是必须能 _catch this specific bug_。
• [ ] Deterministic - 每次运行 verdict 相同（flaky bugs：按上文固定到高复现率）。
• [ ] Fast - 秒级，而不是分钟级。
• [ ] Agent-runnable - 你可以无人值守运行；human in the loop 只能通过 scripts/hitl-loop.template.sh。

如果你发现自己在 command 存在前就读代码构建理论，停下；直接跳到 hypothesis 正是这个 skill 要防止的失败。 没有 red-capable command，就没有 Phase 2。

Phase 2 - Reproduce + minimise

运行 loop。看它变红，也就是 bug 出现。

确认：

• [ ] Loop 产出的 failure mode 是 用户 描述的那个，而不是附近另一个失败。Wrong bug = wrong fix。
• [ ] Failure 能在多次运行中复现（或对于 non-deterministic bugs，复现率足够高，能用来调试）。
• [ ] 你已捕获 exact symptom（error message、wrong output、slow timing），后续阶段可以验证 fix 确实解决它。

Minimise

一旦变红，就把 repro 缩到 仍会变红的最小场景。逐个削减 inputs、callers、config、data 和 steps，每次削减后重新运行 loop；只保留 failure 的 load-bearing 部分。

原因：minimal repro 会缩小 Phase 3 的 hypothesis space（可怀疑的 moving parts 更少），并成为 Phase 5 中干净的 regression test。

完成条件：每个剩余元素都是 load-bearing，移除任意一个都会让 loop 变绿。

在 reproduce 并 minimise 之前不要继续。

Phase 3 - Hypothesise

在测试任何假设前，生成 3-5 个 ranked hypotheses。单假设会锚定在第一个看似合理的想法上。

每个 hypothesis 必须 falsifiable：说明它会做出什么 prediction。

Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."

如果无法说明 prediction，这就是 vibe；丢弃或打磨它。

测试前把 ranked list 展示给用户。 用户常常有 domain knowledge，可以立即重排（"we just deployed a change to #3"），或知道哪些 hypotheses 已被排除。便宜 checkpoint，大幅省时。不要因此阻塞；如果用户 AFK，就按你的排序继续。

Phase 4 - Instrument

每个 probe 都必须映射到 Phase 3 的某个具体 prediction。一次只改变一个变量。

Tool preference：

1. Debugger / REPL inspection，如果环境支持。一个 breakpoint 胜过十条 logs。
2. Targeted logs，放在能区分 hypotheses 的 boundaries。
3. 永远不要 "log everything and grep"。

给每条 debug log 加唯一 prefix，例如 [DEBUG-a4f2]。最后 cleanup 就能一次 grep。未打 tag 的 logs 会存活；带 tag 的 logs 要删除。

Perf branch。 对 performance regressions，logs 通常不对。改为先建立 baseline measurement（timing harness、performance.now()、profiler、query plan），然后 bisect。先 measure，再 fix。

Phase 5 - Fix + regression test

在 fix 前写 regression test，但前提是存在 correct seam。

Correct seam 是 test 能以 call site 中真实发生的方式触发 real bug pattern 的地方。如果唯一可用 seam 太 shallow（bug 需要多个 callers，但 test 只有 single-caller；unit test 无法复制触发 bug 的 chain），那里的 regression test 会给出 false confidence。

如果不存在 correct seam，这本身就是发现。 记录下来。Codebase architecture 阻止你锁住 bug。把它标记给下一阶段。

如果存在 correct seam：

1. 把 minimised repro 变成该 seam 上的 failing test。
2. 看它 fail。
3. 应用 fix。
4. 看它 pass。
5. 重新针对原始（未 minimised）场景运行 Phase 1 feedback loop。

Phase 6 - Cleanup + post-mortem

声明完成前必须做：

• [ ] Original repro 不再复现（重跑 Phase 1 loop）
• [ ] Regression test 通过（或记录缺少 seam）
• [ ] 所有 [DEBUG-...] instrumentation 已移除（grep prefix）
• [ ] Throwaway prototypes 已删除（或移动到明确标记的 debug location）
• [ ] 正确 hypothesis 已写进 commit / PR message，让下一个 debugger 能学习

然后问：什么本可以预防这个 bug？ 如果答案涉及 architecture change（没有好 test seam、callers 缠绕、hidden coupling），带着具体细节交给 /improve-codebase-architecture skill。这个建议要在 fix 之后提出，不要在之前提出；现在你比开始时知道得更多。