A discipline for hard bugs: the one that resists a first glance, the test that fails one run in ten, the regression that crept in between two working versions, or something that got slow. It's an on-ramp: something broken creates the work, and the fix merges onto the main flow.
Its heart is the feedback loop: one command that goes red (fails) on this bug and green once it's fixed, such as a failing test or a curl script. With a tight loop, you will find the cause. Without one, no amount of staring at code will.
Six phases:
Build the loop. Done when one command, already run, drives the bug's code path, asserts the user's exact symptom, is fast, gives the same verdict every run, and the agent can run it unattended.
Reproduce and shrink. Cut inputs and steps one at a time until every piece left is needed.
Guess. List 3 to 5 ranked guesses, each with a prediction that could prove it wrong. Show them to you before testing.
Probe. Change one thing at a time; tag debug logs like [DEBUG-a4f2]. For slowness, measure first, fix second.
Fix. Write the regression test (one that stops this bug coming back) before the fix.
Clean up.
Build the loop.one command that goes red (fails) on this bug and green once it's fixed
Something is broken, failing or slow, and the cause isn't obvious.
A bug appeared between two known states: the loop can drive git bisect run.
A bug happens only sometimes: aim for a higher reproduction rate, not a clean repro.
When not to use it
To build a new behaviour test-first, use tdd. Nothing is broken there.
For raw bug reports other people filed, use triage first.
If you catch yourself reading code to build a theory before the loop exists, stop. That's the exact failure this Skill prevents.
What it needs to start
The user's exact symptom: the error, wrong output or slow timing.
A way to run the code unattended: tests, a dev server, a CLI. If no loop can be built, it stops and asks you for access, a captured log, or permission for temporary production logging.
Secrets hidden: each is shown as <REDACTED>.
What it creates
The loop command and its output.
A regression test that went red, then green. If no correct seam exists (a place where a test can recreate the real bug), that's the finding, and it's noted.
The fix, with the guess that proved right in the commit or pull request message.
No leftover [DEBUG-...] logs or throwaway code.
Then, in the same session, run retro to ask what would have prevented the bug. A missing seam is a job for improve-codebase-architecture.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt's page for the Skill, last updated on 2026-08-24, names the problem in two sentences: "Given a bug report, a coding agent by default reads code and guesses. This skill blocks that." The rule that no theory comes before a loop is the whole point: "That single gate is what the skill is for."
He also says the phases work as locks, not as a to-do list: "The phases are gates, not a checklist." In his words: "The agent cannot enter a phase until a specific condition is true."
How it works underneath
Andreas Zeller's The Debugging Book calls it the scientific method. You invent a hypothesis, then "formulate a prediction that can support or refute the hypothesis", then test that prediction in an experiment, and repeat until nothing disagrees. In his words: "Debugging is a game of falsifying assumptions." So the loop is: form a hypothesis, state a prediction that could refute it, test it in an experiment, then keep or reject the hypothesis.
From snapshot/skills/ask-matt/SKILL.md, line 50: “For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states.”
Matt's guessing phase is the same move with a fixed sentence shape: If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse. A guess with no prediction is, in the Skill's word, "a vibe".
Zeller's own example is in Python. remove_html_markup('<b>"foo"</b>') should return "foo" with its quotes, but it returns foo. The cause, in the line elif c == '"' or c == "'" and tag:, is that "and takes precedence over or". The fix adds brackets: (c == '"' or c == "'") and tag.
Two parts of the Skill plug into older tools:
Bisection.git bisect run reads your command's exit code. Exit 0 means the commit is good. An exit code from 1 to 127, except 125, means it's bad. Exit 125 means the commit "cannot be tested", and bisect skips it. So a loop command that fails only on this bug can drive the whole search alone.
A person in the loop. When only a human can click, the Skill ships a bash template: "The agent runs the script; the user follows prompts in their terminal." At the end, your answers are printed as KEY=VALUE lines for the agent to read.
A real example
On 2026-08-06, Matt merged pull request #779, "fix: make diagnosing-bugs redact secrets". A Snyk audit had flagged the Skill as "W007, HIGH" for insecure credential handling. The pull request lists three ways a live secret could leak:
Phase 1 told the agent to "paste the invocation and its output". For a curl loop, that output includes an Authorization header.
When no loop was possible, it asked you for a captured artifact, such as a HAR file, and those carry auth headers.
The HITL template "prints every capture value back to the terminal, where the agent reads it."
The fix is the Redact section now at the top of the Skill. The pull request, which Matt opened and merged, explains: "The skill's own pressure to produce a red loop is exactly what would push an agent to paste the raw value, so the escape hatch needs writing." That escape hatch is the line "If the redacted output is not enough to diagnose the bug, say so and ask the user."
Matt's page, updated 2026-08-24, calls Snyk's high-risk flag on the Skill a false positive, set off by the shipped .sh file, instructions to run it and outbound HTTP. It doesn't mention the W007 credential finding that the earlier pull request fixed.
Where it goes wrong
It fires on quick questions. Matt's page calls this "the most-reported problem with the skill". In issue #578, opened on 2026-07-15, a user on GPT-5.6-Sol wrote that they were "just describing a problem and hoping for a quick answer", and got a full reproduction loop instead. Matt replied the same day that he "could improve diagnosing-bugs to use a less heavy approach initially and then graduate to a heavier approach if necessary". The issue was open when pinned on 2026-10-30. Until it's fixed, the page's workaround is to say "just answer this, don't diagnose", or to switch off model invocation.
No stop before the fix. Only the guessing phase has a checkpoint with you, and even that one says: "Don't block on it; proceed with your ranking if the user is AFK." So the agent can write code before you agree with its root cause. Matt's page (2026-08-24) says issue #124, which asks for a pause before the fix, "is still open". That's out of date: #124 was closed as not planned on 2026-10-06, and the Skill at the pin commit still has no such pause. The page's advice still holds: "If you want it, say so when you invoke the skill."
Secrets in pasted output, now fixed. The same page says "No instruction tells the agent to sanitise them" and that issue #674 "is open and unimplemented". The page, though updated on 2026-08-24, still describes the Skill from before pull request #779 (merged 2026-08-06), which added the Redact section, and #674 was closed as completed on 2026-10-06. The current SKILL.md decides, and it says: "Redact every secret first".
Old /diagnose prompts break. Version 1.0.0 renamed the Skill from /diagnose, and the old name no longer exists. A saved prompt that calls /diagnose needs updating.
It overlaps with triage. A reader quoted on Matt's page notes that "Triage's step 3 is essentially a shallow, bounded instance of diagnosing-bugs Phase 1–2". Triage's step 3 does say: "For a bug, reproduce it from the reporter's steps." So if a bug came through triage first, the page warns: "expect this skill to redo that work in full".
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), pick one real bug in api/, such as one you hit while building the booking endpoint. Before you start, write down the exact symptom: the error, the wrong output or the slow timing.
Run /diagnosing-bugs with that symptom, and add one line: "Stop and show me the root cause before you write the fix." Then watch the order. Matt's page gives the test: "If theory arrives first, the skill is not running."
Optional: if the bug appeared between two commits, put the loop command in a small script for git bisect run, and make it exit 125 on a commit where the test can't run yet.
Going deeper's Check questions are asked in Next up.
Agent-runnable
From snapshot/skills/diagnosing-bugs/SKILL.md, line 66: “If you catch yourself reading code to build a theory before this command exists, stop: jumping straight to a hypothesis is the exact failure this skill prevents.”
From snapshot/skills/ask-matt/SKILL.md, line 50: “where the real finding is that there's no good seam to lock it down, that's a job for /improve-codebase-architecture.”
From snapshot/web/git-scm.com/docs-git-bisect.md, lines 530–533: “should exit with code 0 if the current source code is good/old, and exit with a code between 1 and 127 (inclusive), except 125, if the current source code is bad/new.”