# CLAUDE.md Recovery Block Paste the block below into your project's CLAUDE.md (or AGENTS.md, .cursorrules, or whatever your agent reads as standing instructions). It changes how the agent behaves the moment debugging starts, before you even write a prompt. Two ways to use it: 1. **Always on:** paste it as-is. Costs a little context on every session, saves you on every bug. 2. **On demand:** keep it in a separate file (e.g. `docs/debug-mode.md`) and tell the agent "read docs/debug-mode.md and follow it" when things go sideways. --- ```markdown ## Debugging rules When we are debugging (a test fails, an error appears, behavior is wrong), switch from building mode to investigation mode. These rules override your defaults until the bug is fixed and regression-tested. ### Investigation before code - Prefer READING code to WRITING code. Before proposing any change, trace the execution path and quote the specific lines involved (file + line). - Never propose a fix until you can state the root cause in two sentences AND explain why the bug presents exactly the way it does (why these inputs, why intermittent, why only in this environment). If you cannot, say what information is missing and how to get it. - If you cannot reproduce the bug with a command or test, your first task is building that reproduction, not fixing anything. ### One hypothesis at a time - State your current hypothesis explicitly before each change. - One hypothesis, one change, one verification run. Never stack a second change on top of an unverified first change. - If a change does not fix the repro, REVERT it before trying the next hypothesis. Do not leave failed-fix debris in the working tree. - After 3 failed hypotheses, stop proposing fixes. Summarize what has been ruled out and recommend either instrumentation, a git bisect, or reverting to the last known-good state. ### Honest verification - Never claim something is fixed without running the reproduction and showing the passing output in the same message. "This should fix it" is banned vocabulary; run it. - Never weaken, skip, delete, or mark-as-expected-failure a test to make the suite pass. If you believe a test itself is wrong, stop and say so; the human decides. - Do not silence errors (empty catch blocks, broad exception handlers, ignoring return codes, @ts-ignore, eslint-disable) as a fix. Silencing a symptom is not fixing a bug. - When the fix works, immediately convert the reproduction into a permanent regression test, and prove it: show the test failing with the fix reverted and passing with the fix applied. ### Minimal footprint - Fixes change the fewest lines that the root cause requires. No refactoring, renaming, dependency bumps, or formatting churn inside a bugfix. Propose cleanups separately, after the fix ships. - Temporary debug logging must carry a "DBG:" prefix and must be removed before the fix is final. Grep for the prefix to confirm. - Never log secrets or full user records while instrumenting; redact to shape and length. ### Escalation honesty - If evidence points outside the code you can see (third-party outage, data corruption, infra config), say so directly instead of changing application code to route around a mystery. - If we have been debugging one bug for a long stretch with rising diff size and no confirmed root cause, recommend `git stash` or reset to the last known-good commit and a fresh start with a better reproduction. Recommending a reset is a valid and welcome answer. ``` --- Part of the Debug Loop resource. Trim rules you disagree with; standing instructions only work if you actually mean them.