Claude’s default response to a bug report is a fix. Read the description, pattern-match to a known class of problem, propose a solution. This works often enough to feel reliable. It fails silently when the description is incomplete, when the real cause is not the obvious cause, or when the fix addresses a symptom.
The diagnose skill enforces the debug loop before a fix is proposed.
The loop
reproduce → minimise → hypothesise → instrument → fix → regression testEach step is a gate. The next step doesn’t start until the current one is done.
reproduce
Confirm the bug exists in a controlled context. Not “the user reported X” — run the code, observe the failure. If it can’t be reproduced, the session stops here and asks why.
minimise
Reduce the reproduction case to the smallest input that still triggers the failure. This step is skipped constantly. It matters because the minimal case often reveals that the assumed cause is wrong.
hypothesise
Generate candidate causes ranked by likelihood. More than one. The first hypothesis is usually the obvious one. The second and third are where the real cause often lives.
instrument
Add observability targeted at the hypotheses. Logs, assertions, intermediate output — whatever surfaces the execution path. This step rejects “let’s try this fix and see” as a debugging strategy.
fix
Apply the fix only after instrumentation confirms which hypothesis is correct.
regression test
Write a test that would have caught this bug. If the test can’t be written, record why.
Usage
/diagnose orders are missing from the report after 2026-05-01The skill runs the loop as a structured conversation. It won’t skip to a fix. It will ask for reproduction steps if none are provided.
Why enforcement is needed
The loop is not novel. Every debugging methodology converges on roughly the same steps. The problem is execution under time pressure — or under a tool that’s optimised to produce output quickly.
Without enforcement, the sequence becomes: describe problem → receive fix → apply fix → observe that it didn’t work → describe the new symptom → receive another fix. This is expensive and produces no understanding of the system.
The loop is slower at the start. It’s faster overall because each step produces information that makes the next step cheaper.
When to skip the full loop
Bugs with a known, unambiguous cause — a missing null check, a wrong comparison operator visible in a stack trace — don’t need the full loop. The skill recognises these and shortens accordingly. The loop is for bugs where the cause is not visible from the description.