Diagnose 是一个处理困难 bug 的纪律化诊断方法,按阶段推进,只有在理由明确时才跳过阶段。
用途
它主要用于排查棘手的 bug 和性能回退(performance regression)。整套流程围绕一个核心目标展开:建立一个能够覆盖该 bug 的快速、确定、agent 可运行的 pass/fail 信号(反馈环)。作者认为,只要有了这个信号,后续的二分查找(bisection)、假设验证和插桩都只是对这个信号的消费;没有它,长时间盯着代码也无法解决问题。
主要能力(各阶段)
Phase 1 — 构建反馈环 这是整个 skill 的核心。构造反馈环的方式按大致顺序可尝试:在能触达 bug 的 seam 上写 failing test(unit、integration 或 e2e);针对运行中的 dev server 写 Curl / HTTP script;带 fixture input 的 CLI 调用并把 stdout 与已知正确的 snapshot 做 diff;用 Headless browser script(Playwright / Puppeteer)驱动 UI 并断言 DOM/console/network;重放捕获的 trace(把真实 network request、payload 或 event log 存盘后隔离重放);搭建一次性 harness(启动系统最小子集,用一次函数调用触发 bug 路径);property / fuzz loop(对“有时输出错误”的 bug 运行大量随机输入寻找失败模式);bisection harness(bug 出现在两个已知状态之间时,自动化启动、检查、重复,以便 git bisect run);differential loop(对同一输入运行新旧版本或两组配置并 diff 输出);最后手段是 HITL bash script,用 scripts/hitl-loop.template.sh 驱动人,让循环仍然结构化并回传捕获输出。
反馈环本身也要迭代优化:让它更快(缓存 setup、跳过无关 init、缩小 test scope)、信号更尖锐(断言具体症状而非“没有崩溃”)、更确定(固定时间、固定 RNG seed、隔离 filesystem、冻结 network)。作者指出,30 秒且 flaky 的循环只比没有循环好一点点,2 秒且确定的循环才是调试超能力。
对于非确定性 bug,目标不是干净复现,而是提高复现率:把触发器循环 100 次、并行化、加压、缩窄 timing windows、注入 sleeps。50% flake 的 bug 可以调试,1% 不行。确实无法构建循环时,应停下来并明确说明,列出尝试过的方式,向用户请求可复现环境的访问权限、捕获的 artifact(HAR file、log dump、core dump、带时间戳的 screen recording)或添加临时 production instrumentation 的许可;不要在没有循环时继续 hypothesise。在拥有可信循环之前,不进入 Phase 2。
Phase 2 — 复现 运行循环,看到 bug 出现,并确认循环产生的是用户描述的 failure mode 而非附近另一个失败,失败可在多次运行中复现(非确定性 bug 则复现率足够高),且已捕获精确症状(error message、wrong output、slow timing),以便后续验证修复。复现之前不继续。
Phase 3 — 假设 在测试任何假设前,先生成 3-5 个排序后的 hypotheses,避免锚定在第一个看起来合理的想法上。每个假设必须可证伪,说明它产生的预测,格式为:“If is the cause, then will make the bug disappear / will make it worse.”说不岀预测就丢掉或收紧。测试前把排序列表展示给用户,因为他们通常有 domain knowledge 可以瞬间重排,或知道哪些假设已被排除;这个 checkpoint 便宜但省时,且不阻塞,用户 AFK 时按自己的排序继续。
Phase 4 — 插桩 每个 probe 都必须映射到 Phase 3 中的一个具体预测,一次只改一个变量。工具偏好上,环境支持时优先用 Debugger / REPL inspection,一个 breakpoint 胜过十条 log;在能区分 hypotheses 的边界上加 targeted logs,永远不要“log everything and grep”;给每条 debug log 加唯一前缀(如 [DEBUG-a4f2]),最后清理只需一次 grep。对性能回退,logs 通常不合适,应先建立 baseline measurement(timing harness、performance.now()、profiler、query plan),再 bisect,先测量再修复。
Phase 5 — 修复 + 回归测试 在 fix 之前写 regression test,但前提是存在正确的 seam:该 test 能在 call site 复现真实 bug pattern。如果唯一可用的 seam 太浅(bug 需要多个 caller 但测试只有单一 caller,或 unit test 无法复制触发 bug 的链路),那里的 regression test 会带来虚假信心。如果没有正确 seam,这本身就是发现,应记录并标记到下一阶段。存在正确 seam 时:把最小化 repro 转成该 seam 上的 failing test,看它失败,应用 fix,看它通过,然后针对原始(未最小化)场景重新运行 Phase 1 反馈环。
Phase 6 — 清理 + post-mortem 宣布完成前必须做:原始 repro 不再复现(重新运行 Phase 1 loop);regression test 通过(或已记录没有 seam);所有 [DEBUG-...] instrumentation 已删除(grep 前缀);throwaway prototypes 已删除或移到明确标记的 debug 位置;在 commit / PR message 中说明最终正确的 hypothesis,方便下一个调试者学习。随后追问:什么本可以防止这个 bug?如果答案涉及 architecture change(没有好的 test seam、callers 缠绕、隐藏 coupling),可带着具体信息交给 /improve-codebase-architecture skill。建议应在 fix 落地后提出,而非之前。
使用方式 通过 skill 触发使用,用户说 “diagnose this” / “debug this” 等即可。具体安装命令与运行方式暂未提供。
适用场景 难以复现或非确定性的 bug、性能回退、需要系统化定位根因且希望留下回归测试的调试工作。
限制 原文未提供该 skill 支持的平台、依赖环境、收费或价格等信息,暂未提供。