# Diagnosing Bugs

面向棘手缺陷和性能回退的诊断循环。适用于用户说 “diagnose” / “debug this”，或报告某些东西 broken、throwing、failing、slow 时。

- Repository: https://github.com/vinvcn/mattpocock-skills-zh-CN (5461 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill diagnosing-bugs -g -a claude-code -y`
Codex: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill diagnosing-bugs -g -a codex -y`
Cursor: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill diagnosing-bugs -g -a cursor -y`
Gemini CLI: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill diagnosing-bugs -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add vinvcn/mattpocock-skills-zh-CN`

## Description

面向棘手缺陷和性能回退的诊断循环。适用于用户说 “diagnose” / “debug this”，或报告某些东西 broken、throwing、failing、slow 时。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 诊断缺陷

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

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

## 脱敏

这个 skill 会要求你展示 commands、outputs 和捕获的 artifacts。**先 redact 掉每个 secret**：用 `<REDACTED>` 替换。Build loops 要针对 env vars 进行，让 credential 留在 environment 里而不是你展示的内容中。捕获的 artifacts 带有 auth headers：只引用携带 signal 的那些行。

如果 redact 后的 output 不足以诊断 bug，就说明情况并询问用户。

## Phase 1 - 构建 feedback loop

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

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

### 构建 loop 的方式 - 大致按以下顺序尝试

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%。

### 收紧 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 的调试超能力。

### 非确定性 bugs

The rest: https://github.com/vinvcn/mattpocock-skills-zh-CN/blob/HEAD/skills/engineering/diagnosing-bugs/SKILL.md