菜单
A feedback-loop-first discipline for diagnosing hard bugs and performance regressions. Use when the user reports something broken, throwing, failing, flaky, or slow, or asks to "diagnose", "debug this", "原因を調べて".
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
A relentless one-question-at-a-time interview that sharpens a plan, decision, or idea until shared understanding is reached — not limited to software. Use when the user wants requirements or a decision clarified before acting, wants to stress-test their thinking, or asks to "grill me", "詰めて", "brainstorm this".
Executes an implementation plan or agreed work by orchestrating fresh subagents — one implementer per task, a reviewer between tasks — while the main model plans, briefs, and evaluates without writing code itself. Use when the user asks to "implement the plan", "start implementation", "実装して", or hands over a plan or spec to execute.
Builds a clearly-marked throwaway prototype to answer a design question before committing to an implementation. Use when the user wants to sanity-check whether logic or a state model feels right, explore what a UI should look like, or asks to "prototype this", "試作して".
Creates an Architecture Decision Record for a decision that is hard to reverse, surprising without context, and the result of a real trade-off. Use when such a decision has just been made, or the user asks to "record this decision", "ADRにして", or mentions decision records.
Reviews the diff since a fixed point along two axes run as parallel subagents — Spec (does the change match what was asked?) and Standards (repo conventions plus a code-smell baseline) — and reports them side by side. Use when the user asks to review a branch, work-in-progress changes, a diff, or "review since X".
Configures this repository for the engineering skills by writing .claude/engineering.local.md — where specs, plans, and ADRs are saved, if at all — and excluding it from git locally. Run once per repository before relying on doc-saving skills.
| name | diagnose-bug |
| description | A feedback-loop-first discipline for diagnosing hard bugs and performance regressions. Use when the user reports something broken, throwing, failing, flaky, or slow, or asks to "diagnose", "debug this", "原因を調べて". |
A discipline for hard bugs and performance regressions. Skip phases only when explicitly justified.
This is the skill. Everything else — bisection, hypothesis-testing, instrumentation — just consumes a tight pass/fail signal once you have one. Reading code to build a theory before that signal exists is the failure this skill prevents: stop and come back here.
Construct one, roughly in this order of preference: a failing test at whatever seam reaches the bug, a curl/CLI invocation diffed against a known-good snapshot, a headless browser script asserting on DOM/console/network, a replayed captured trace, a throwaway harness exercising the bug path in isolation, or a bisection/differential loop comparing two states or configs.
Once you have a loop, tighten it: faster (skip unrelated init, narrow scope), sharper (assert the specific symptom, not "didn't crash"), more deterministic (pin time, seed RNG, isolate filesystem/network). For non-deterministic bugs, aim for a higher reproduction rate rather than a clean repro — loop the trigger many times, parallelize, narrow timing windows, until the failure is frequent enough to debug against.
Phase 1 is done when you can name one command — already run, output pasted — that is red-capable (catches this specific bug, not just "errors"), deterministic, fast, and agent-runnable. If you genuinely cannot build a loop, say so explicitly, list what you tried, and ask the user for environment access or a captured artifact rather than proceeding to hypothesize without one.
Run the loop and confirm it produces the failure mode the user actually described, not a different one nearby.
Then shrink the repro to the smallest scenario that still goes red: cut inputs, callers, config, and steps one at a time, re-running after each cut. Done when every remaining element is load-bearing — removing any one of them makes the loop go green. This narrows the hypothesis space in Phase 3 and becomes the regression test in Phase 5.
Generate 3–5 ranked hypotheses before testing any of them; a single hypothesis anchors on the first plausible idea. Each must be falsifiable: "If X is the cause, changing Y makes it disappear." Discard or sharpen anything you can't state as a prediction.
Show the ranked list to the user before testing — they often re-rank instantly with domain knowledge, or know hypotheses already ruled out. Don't block on a response if they're unavailable.
Each probe should map to a specific prediction from Phase 3, changing one variable at a time. Prefer a debugger or REPL inspection over logs — one breakpoint beats ten logs. When logs are the only option, tag each with a unique prefix (e.g. [DEBUG-a4f2]) so cleanup is a single grep.
For performance regressions, logs are usually misleading. Measure a baseline first (timing harness, profiler, query plan), then bisect against it.
Write the regression test before the fix, but only if a correct seam exists — one where the test exercises the real bug pattern as it occurs at the call site, not a shallow substitute. If no correct seam exists, that's itself a finding: note it, the architecture is preventing the bug from being locked down.
When a seam exists: turn the minimised repro into a failing test there, watch it fail, apply the fix, watch it pass, then re-run the Phase 1 loop against the original, unminimised scenario.
Before declaring done: the original repro no longer reproduces, the regression test passes (or the missing seam is documented), all [DEBUG-...] instrumentation is removed, and the hypothesis that turned out correct is stated in the commit message so the next debugger learns.
An architectural cause behind the bug — no good seam, tangled callers — is worth recording; record-adr is a candidate.
