| name | diagnosing-bugs |
| description | 面向棘手缺陷和性能回退的诊断循环。适用于用户说 “diagnose” / “debug this”，或报告某些东西 broken、throwing、failing、slow 时。 |
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
- Failing test，放在能触达 bug 的 seam 上：unit、integration、e2e 都可以。
- Curl / HTTP script，打到运行中的 dev server。
- CLI invocation，使用 fixture input，并把 stdout 与 known-good snapshot diff。
- Headless browser script（Playwright / Puppeteer），驱动 UI，并断言 DOM/console/network。
- Replay a captured trace. 把真实 network request / payload / event log 保存到磁盘，并在隔离环境中 replay 到代码路径。
- Throwaway harness. 启动系统的最小子集（一个 service、mocked deps），用一次 function call 触发 bug code path。
- Property / fuzz loop. 如果 bug 是 "sometimes wrong output"，运行 1000 个 random inputs 并寻找 failure mode。
- Bisection harness. 如果 bug 出现在两个已知状态之间（commit、dataset、version），自动化 "boot at state X, check, repeat"，这样可以
git bisect run。
- Differential loop. 用同一 input 跑 old-version vs new-version（或两个 configs），然后 diff outputs。
- 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），且它满足：
如果你发现自己在 command 存在前就读代码构建理论，停下；直接跳到 hypothesis 正是这个 skill 要防止的失败。 没有 red-capable command，就没有 Phase 2。
Phase 2 - Reproduce + minimise
运行 loop。看它变红，也就是 bug 出现。
确认：
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 is the cause, then will make the bug disappear / 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：
- Debugger / REPL inspection，如果环境支持。一个 breakpoint 胜过十条 logs。
- Targeted logs，放在能区分 hypotheses 的 boundaries。
- 永远不要 "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：
- 把 minimised repro 变成该 seam 上的 failing test。
- 看它 fail。
- 应用 fix。
- 看它 pass。
- 重新针对原始（未 minimised）场景运行 Phase 1 feedback loop。
Phase 6 - Cleanup + post-mortem
声明完成前必须做：
然后问：什么本可以预防这个 bug？ 如果答案涉及 architecture change（没有好 test seam、callers 缠绕、hidden coupling），带着具体细节交给 /improve-codebase-architecture skill。这个建议要在 fix 之后提出，不要在之前提出；现在你比开始时知道得更多。
