Systematic debugging

Skill yinqd3/workbuddy-skills/superpowers/systematic-debugging

A curated collection of WorkBuddy agent skills — academic pipeline, frontend slides, PPTX generator, tool-call repair, and more.

Install

npx -y skills add yinqd3/workbuddy-skills --skill systematic-debugging

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

遇到任何 bug、测试失败或意外行为时使用，在提出修复方案之前。铁律：没有根因调查，不许提修复方案。触发词：bug、报错、不工作、出问题了、fix、debug、排查、怎么回事。

SKILL.md

2.8 KB, as published. Nobody here has run it

系统化调试

核心原则

总是先找到根因再尝试修复。 症状修复 = 失败。随机修复浪费时间并制造新 bug。

铁律

没有根因调查 = 没有修复

没完成阶段 1，不能提修复方案。

何时使用

任何技术问题：

测试失败
生产 Bug
意外行为
性能问题
构建失败
集成问题

尤其在以下情况必须使用：

时间紧迫时（紧急情况最容易想猜）
"就改一下"看起来很明显
已经试过多次修复
上次修复没起作用
你不完全理解这个问题

四阶段调试法

必须完成每个阶段再进入下个阶段。

阶段 1：根因调查

在尝试任何修复之前：

仔细读错误信息
- 不要跳过错误或警告
- 完整读堆栈跟踪
- 注意行号、文件路径、错误码
稳定复现
- 能可靠触发吗？
- 精确步骤是什么？
- 每次都发生吗？
- 如果不能复现 → 收集更多数据，不要猜
检查最近的变更
- 什么改变可能导致这个？
- git diff、最近的提交
- 新依赖、配置变更
- 环境差异

多组件系统的证据收集

在每个组件边界:
  - 记录什么数据进入
  - 记录什么数据出来
  - 验证配置/环境传播
跑一次看哪里断了，然后再深入那层

追踪数据流
- 错误值的起源在哪里？
- 谁用错误值调用了这个？
- 向上追踪调用栈直到找到源头
- 在源头修复，不在症状处修复

阶段 2：模式分析

找到模式再修复：

在代码库中找类似的工作示例
完整对照参考——不要略读
列出工作与失败之间的每个差异
理解所有依赖和假设

阶段 3：假设+检验

形成一个清晰的假设："我认为 X 是根因，因为 Y"
明确写下来
设计最小测试来证明/否定它
跑测试
如果被否定 → 形成新假设，重复
如果被证明 → 进入修复

阶段 4：修复+验证

在根因处修复，不在症状处
写一个能捕获这个 bug 的测试
验证修复有效
验证无回归（全量测试套件）
清晰提交信息，解释根因

反模式

"试试这个" — 没有根因的随机修复
"大概是 X" — 没有证据的猜测
"快速补丁" — 症状修复，根因还在
一次改多个东西 — 无法知道哪个起效
跳过复现 — 调试一个不能稳定触发的问题