debug · git:20261114.fa8b3c3 · 2026-11-14 · sha256 9a88a8880108c9ac
debug git:20261114.fa8b3c3A
Immutable. This exact content never changes and is served at /api/v1/blob/9a88a8880108c9ac.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_jvryfztgbdjzelkp/9a88a8880108c9ac747921f2e91bc7e77565ad26cb5d652e92b3abfe9c302b30.json
Then /plugin install debug@markdownregistry-jvryfztgbdjzelkp in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: debug description: Use when you diagnose a bug, a flaky test, unexpected behavior or a production incident, before you propose or write a fix. --- # Debug NO FIXES WITHOUT ROOT CAUSE. This is a hard rule. A fix without a root cause is a guess that changed the symptom. If you want to change code to remove a bug and you cannot state its root cause, stop. ## Do not - Do not change code as a fix before a repro exists. A repro shows the bug on demand. - Do not claim a behavior (what happens, when, how often) without the exact command and its output in the same message. - Do not try a fourth fix at a site where three fixes failed. The defect is upstream. Go back to the design. - Do not close a production incident without an open root-cause item. The item names an owner and a next step. Mitigation is never the end. ## Make a repro first Before you make a theory, build a repro. A repro is a command whose output changes with the hypothesis that is true. Use the cheapest one that separates the hypotheses, for example a failing test, `curl`, a log search or `git bisect`. Run a subagent's claim about the bug again before you repeat it. ## Hypotheses Write each hypothesis when you make it, in the plan file or in the report: ``` HYP <n>: <hypothesis> → <experiment> → <result> ``` - Add instruments at the boundary between the two sides that you want to separate. - Mark temporary logs with `DBG-<topic>`. Before each commit, run `grep -rn "DBG-" <path>` until it finds nothing. - After thirty minutes without a narrower hypothesis, write down the current state. Then read the code path again from the top before the next attempt. - At the end of each session, write the state of the hypotheses, even "no narrower hypothesis yet". ## Incident: stabilize first When failures occur in production now, stop the failures before you diagnose. Use the fastest method: turn a flag off, roll back, or pause the queue. Then open the root-cause item with an owner and a specific next step. ## Rationalizations | Thought | Reality | |---|---| | "The fix is obvious, skip root cause" | Symptom fixes come back. Find the cause. | | "One more print will crack it" | No hypothesis, no instrument. Write the HYP line first. | | "It's in prod, just ship the real fix now" | Stop the failures first. The root cause comes next, as an owned item. Never skip it. | | "I've patched this spot before, one more try" | Three failed fixes here mean the defect is upstream. Stop the patches. Go up to the design. |