# CLAUDE.md: Debugging workflow

Use this whenever the task is "fix this bug", "this is broken", or an error message.

## 1. Reproduce
- Get the exact error, stack trace, inputs, and environment. Run the failing command yourself.
- Turn the reproduction into a failing automated test when possible. If you can't reproduce it, say so and ask for more detail instead of guessing.

## 2. Isolate
- Read the stack trace from the top frame in our code. Open the actual files; don't assume what they contain.
- Narrow it down: smaller input, `git log -p` / `git bisect` for regressions, targeted logging around the suspect code.

## 3. Hypothesize
- Write down one or two hypotheses with the evidence for each. Pick the cheapest one to test.
- Test one variable at a time. Remove temporary logs afterward.

## 4. Fix the cause
- Fix the root cause, not the symptom. No blanket `try/catch`, `?.` chains, retries, or longer timeouts unless they *are* the right fix, and explain why.
- Check for the same bug pattern elsewhere (`rg` for similar code).

## 5. Verify
- The reproduction test now passes, the full suite passes, and the original command works.

## Report
Root cause (one paragraph), the fix, how it was verified, and any related risks.

## Don't
- Don't change multiple things at once and hope.
- Don't delete or skip failing tests to "fix" a build.