Build a repeatable signal for the exact failure, narrow the reproduction, test hypotheses and verify the fix.
Install and prepare
Run the following in your project terminal, then use the prompt below in Claude Code. This installs editable, project-scoped skill files.
npx skills@latest add mattpocock/skills --skill diagnosing-bugs --agent claude-code
For Codex, replace claude-code with codex in the command and /diagnosing-bugs with $diagnosing-bugs in the prompt. With the complete Claude Code plugin, select /mattpocock-skills:diagnosing-bugs instead; avoid installing the same skills twice.
You need a runnable environment, triggering steps and an expected result. Bring a small input or sanitized log; performance regressions also need measurement conditions and a baseline.
Your first task
Adapt the scenario and paths to your project, then enter this in the agent conversation:
/diagnosing-bugs
Clicking checkout twice creates two orders in local development. One purchase should create one order. First build a check that catches duplicate orders, then diagnose the cause.
Work through the task
Build a symptom-specific check
Choose the shortest useful route: a test, an HTTP request or a browser action. For duplicate orders, assert the number of orders or the idempotent result. A clickable button or successful status code cannot catch this bug. Observe the actual failure before discussing causes.
Minimize and compare hypotheses
Remove one condition at a time while preserving the failure. Then compare plausible causes such as repeated submission, missing idempotency or a transaction race. Each hypothesis should predict a measurable difference. This makes the next experiment useful even when the first theory is wrong.
Return to the original scenario
Keep a regression check at a boundary that reaches the real failure. Apply the smallest justified fix and rerun it, then repeat the original double-click scenario. A minimized test can miss surrounding interactions. Remove temporary probes and preserve the explanation of the root cause.
Check the result
The check should fail before the fix, pass afterward and address the original symptom. For intermittent failures, record the reproduction rate and missing environment details instead of treating one quiet run as an explanation.
Common questions
It cannot reproduce the problem. Supply the triggering input, environment differences or a minimal log.
It starts a full workflow for a quick question. Say that you want an explanation before a diagnosis.
What about performance? Fix the dataset and timing method before comparing changes.
Start an intermittent import bug with evidence
Suppose a CSV import sometimes writes one row twice. Ask: “Use diagnosing-bugs on the duplicate rows after retrying import.csv. First build and run a command with a fixed fixture that counts duplicate record IDs and shows a red result. Do not guess queue or database causes yet.” The feedback loop should report IDs and counts. If only one run in a hundred fails, increase reproduction rate before changing production logic.
Then test client retry, duplicate job delivery, and database uniqueness as separate falsifiable hypotheses. A command that merely exits successfully cannot detect the reported duplicate; assert on the business result. After a fix, keep a regression check at the real call boundary and repeat the original retry sequence. If the test is green but the user path still duplicates rows, the test seam was too shallow.
Distinguish a quick explanation from full diagnosis
A user found that diagnosing-bugs sometimes auto-triggered for a quick code question and spent time building a low-value mock reproduction. If you only need an explanation, say “give an initial reading without a full diagnosis.” For a user-facing defect that needs a fix, provide the original failing path and business assertion so the feedback loop tests the real failure rather than an invented mock case.