Agent skill

Diagnosing Bugs

by vinvcn in vinvcn/mattpocock-skills-zh-CN

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

MITAuto-check passedTesting & QA

Install Diagnosing Bugs

skills CLI
$ npx skills add vinvcn/mattpocock-skills-zh-CN --skill diagnosing-bugs -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install vinvcn/mattpocock-skills-zh-CN diagnosing-bugs --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/vinvcn/mattpocock-skills-zh-CN.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/engineering/diagnosing-bugs .claude/skills/diagnosing-bugs && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
diagnosing-bugs
GitHub stars
4.7k
Token cost
~1.4k tokens
SKILL.md length
626 words
Files
3 (incl. scripts)
Skills in repo
32
Repo updated
First seen
Licence
MIT

At a glance

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

  • Works in 6 steps: 构建 feedback loop → 复现 + 最小化 → 形成假设 → …
  • Testing & QA work in your project
  • SKILL.md covers 脱敏, Phase 1 - 构建 feedback loop, Phase 2 - 复现 + 最小化 and Phase 3 - 形成假设, plus 3 more sections
  • Runs Shell scripts from its folder; calls git

What it does

Diagnosing Bugs is an agent skill from vinvcn/mattpocock-skills-zh-CN. 面向棘手缺陷和性能回退的诊断循环。适用于用户说 “diagnose” / “debug this”,或报告某些东西 broken、throwing、failing、slow 时。

Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files, including scripts (for example `agents/openai.yaml` and `scripts/hitl-loop.template.sh`).

It sits in Testing & QA. The repository describes itself as: 这是 mattpocock/skills 的简体中文本地化版本。 The licence is MIT.

When your agent uses it

  • Testing & QA work in your project

Example prompts

  • “diagnose”
  • “debug this”
  • “/diagnosing-bugs”

Requirements

  • A Bash shell

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. 构建 feedback loop
  2. 复现 + 最小化
  3. 形成假设
  4. 插桩
  5. 修复 + regression test
  6. 清理

What it can do on your machine

Read from SKILL.md and the folder at commit bf98e53. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Shell), which the agent can run.

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Diagnosing Bugs loads about 1.4k tokens when it runs. Until then it costs about 26 tokens; SKILL.md has 626 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~26
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from vinvcn/mattpocock-skills-zh-CN at commit bf98e53, republished under its MIT licence (© vinvcn). 626 words, ~1,363 tokens.

Download SKILL.mdSave it as .claude/skills/diagnosing-bugs/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
diagnosing-bugs
description
面向棘手缺陷和性能回退的诊断循环。适用于用户说 “diagnose” / “debug this”,或报告某些东西 broken、throwing、failing、slow 时。

诊断缺陷

面向棘手 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

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

当你确实无法构建 loop 时

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

完成条件 - 能变红的 tight loop

Phase 1 完成条件:loop tight 且 red-capable。你能指出 一个 command(script path、test invocation、curl),并且你已经至少运行过一次(展示 invocation 和 output,已 redact),且它满足:

  • 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 - 复现 + 最小化

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

确认:

  • Loop 产出的 failure mode 是 用户 描述的那个,而不是附近另一个失败。Wrong bug = wrong fix。
  • Failure 能在多次运行中复现(或对于 non-deterministic bugs,复现率足够高,能用来调试)。
  • 你已捕获 exact symptom(error message、wrong output、slow timing),后续阶段可以验证 fix 确实解决它。
Show full SKILL.md (261 more words)Show less
最小化

一旦变红,就把 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 - 形成假设

在测试任何假设前,生成 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 - 插桩

每个 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 - 修复 + 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 - 清理

声明完成前必须做:

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

© vinvcn, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (scripts) in skills/engineering/diagnosing-bugs of vinvcn/mattpocock-skills-zh-CN.

  • SKILL.md
  • agents/openai.yaml
  • scripts/hitl-loop.template.sh

Open the folder on GitHubat commit bf98e53

Compare with similar skills

Diagnosing Bugs next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Diagnosing Bugs compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Diagnosing Bugs this skillvinvcn/mattpocock-skills-zh-CN4.7k—~1.4kAutomated safety check: PassMIT
Web Application Testinganthropics/skills180k51 repos~966Automated safety check: PassApache-2.0
Diagnosing Bugsfossasia/eventyay-interpretation1.6k32 repos~2.1kAutomated safety check: PassApache-2.0
TDDpietheinstrengholt/rssmonster56430 repos~906Automated safety check: PassMIT
TDD WorkflowhellangleZ/burn-in-cceverywhere-ralph11211 repos~2.4kAutomated safety check: PassNone
TDDsanity-io/sanity6.4k20 repos~1kAutomated safety check: PassMIT

Similar skills

  • Web Application Testing

    anthropics/skills

    Official

    Tests local web applications with Python Playwright scripts, checking frontend behavior, capturing screenshots and reading browser console logs.

    180k GitHub starsUsed in 51 repos~966 tokens
    Testing & QAAuto-check passed
  • Diagnosing Bugs

    fossasia/eventyay-interpretation

    Diagnosis loop for hard bugs and performance regressions. An agent skill from fossasia/eventyay-interpretation.

    1.6k GitHub starsUsed in 32 repos~2.1k tokens
    Testing & QAAuto-check passed
  • TDD

    pietheinstrengholt/rssmonster

    Test-driven development. An agent skill from pietheinstrengholt/rssmonster.

    564 GitHub starsUsed in 30 repos~906 tokens
    Testing & QAAuto-check passed
  • TDD Workflow

    hellangleZ/burn-in-cceverywhere-ralph

    A skill your agent uses when writing new features, fixing bugs, or refactoring code.

    112 GitHub starsUsed in 11 repos~2.4k tokens
    Testing & QAAuto-check passed
  • TDD

    sanity-io/sanity

    Official

    Test-driven development with red-green-refactor loop. An agent skill from sanity-io/sanity.

    6.4k GitHub starsUsed in 20 repos~1k tokens
    Testing & QAAuto-check passed
  • Context Driven Development

    Ibrahim-3d/orchestrator-supaconductor

    A skill your agent uses when working with Conductor's context-driven development methodology, managing project context artifacts, or understanding the relationship between product.md, tech-stack.md…

    381 GitHub starsUsed in 9 repos~2.9k tokens
    Testing & QAAuto-check passed

More from vinvcn/mattpocock-skills-zh-CN

All 32 skills in this repo
  • Git Guardrails Claude Code

    vinvcn/mattpocock-skills-zh-CN

    设置 Claude Code hooks,在危险 git commands(push、reset --hard、clean、branch -D 等)执行前阻止它们。适用于用户想防止破坏性 git 操作、添加 git safety hooks,或在 Claude Code 中阻止 git push/reset 时。

    4.7k GitHub stars~461 tokensUpdated yesterday
    Auto-check passed
  • Codebase Design

    vinvcn/mattpocock-skills-zh-CN

    用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航,或其他技能需要深模块词汇时。

    4.7k GitHub stars~1.1k tokensUpdated yesterday
    Auto-check passed
  • Domain Modeling

    vinvcn/mattpocock-skills-zh-CN

    构建并打磨项目的领域模型。适用于讨论 codebase 术语、编写或编辑 GLOSSARY.md,或记录或编辑 ADR。

    4.7k GitHub stars~477 tokensUpdated yesterday
    Auto-check passed
  • Migrate To Shoehorn

    vinvcn/mattpocock-skills-zh-CN

    将测试文件从 as 类型断言迁移到 @total-typescript/shoehorn。适用于用户提到 shoehorn、想替换测试中的 as,或需要局部测试数据时。

    4.7k GitHub stars~603 tokensUpdated yesterday
    Auto-check passed
  • PR

    vinvcn/mattpocock-skills-zh-CN

    用于撰写 PR 正文。适用于用户要求起草、改写或改进 PR 正文,或希望 PR 更便于审阅时. An agent skill from vinvcn/mattpocock-skills-zh-CN.

    4.7k GitHub stars~729 tokensUpdated yesterday
    Auto-check passed
  • Scaffold Exercises

    vinvcn/mattpocock-skills-zh-CN

    创建包含章节、题目、答案和讲解的练习目录结构,并确保通过 linting。适用于用户想 scaffold exercises、创建 exercise stubs,或设置新的课程章节时。

    4.7k GitHub stars~748 tokensUpdated yesterday
    Auto-check passed

Categories

Questions about Diagnosing Bugs

What does Diagnosing Bugs do?

面向棘手缺陷和性能回退的诊断循环。适用于用户说 “diagnose” / “debug this”,或报告某些东西 broken、throwing、failing、slow 时。. Diagnosing Bugs is an agent skill from vinvcn/mattpocock-skills-zh-CN.

When should I use Diagnosing Bugs?

Diagnosing Bugs fits situations like: testing & QA work in your project.

How do I install Diagnosing Bugs in Claude Code?

Run `npx skills add vinvcn/mattpocock-skills-zh-CN --skill diagnosing-bugs -a claude-code`. Or copy the skill folder (skills/engineering/diagnosing-bugs in vinvcn/mattpocock-skills-zh-CN) into .claude/skills/diagnosing-bugs in your project. Claude Code loads it when a task matches its description.

How do I install Diagnosing Bugs in Codex?

Run `npx skills add vinvcn/mattpocock-skills-zh-CN --skill diagnosing-bugs -a codex`. Or copy the skill folder (skills/engineering/diagnosing-bugs in vinvcn/mattpocock-skills-zh-CN) into .agents/skills/diagnosing-bugs in your project. Codex loads it when a task matches its description.

Can I use Diagnosing Bugs in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add vinvcn/mattpocock-skills-zh-CN --skill diagnosing-bugs -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/diagnosing-bugs, .gemini/skills/diagnosing-bugs, .github/skills/diagnosing-bugs and .opencode/skills/diagnosing-bugs in your project.

What does Diagnosing Bugs need to run?

Going by SKILL.md and its folder, Diagnosing Bugs needs a shell for the scripts in its folder and the command-line tools its instructions call (git). Our summary lists: A Bash shell.

Does Diagnosing Bugs access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Diagnosing Bugs safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Diagnosing Bugs use?

Diagnosing Bugs is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Diagnosing Bugs use?

About 1.4k tokens (SKILL.md is roughly 5.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Diagnosing Bugs?

Skills that share tags, products or a category with Diagnosing Bugs: Web Application Testing (anthropics/skills, 180k stars), Diagnosing Bugs (fossasia/eventyay-interpretation, 1.6k stars), TDD (pietheinstrengholt/rssmonster, 564 stars) and TDD Workflow (hellangleZ/burn-in-cceverywhere-ralph, 112 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Diagnosing Bugs?

vinvcn (a GitHub user) maintains it in vinvcn/mattpocock-skills-zh-CN, which has 4,682 GitHub stars. The repository holds 32 skills in this directory. The repository was last updated on October 8, 2026.

Source: vinvcn/mattpocock-skills-zh-CN on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.