Debugging

---
name: Debugging
description: Find root causes, not symptoms.
---
# Debugging

Form a hypothesis before you change code. "Let me just try X" debugging feels productive but corrupts the codebase and often masks the real fault, which then resurfaces later.

## Method
1. **Reproduce reliably.** A bug you can't reproduce is one you can't confirm fixed. Find the minimal steps or input that triggers it every time.
2. **Bisect.** If reproduction is recent, `git bisect` to the exact commit. This is often faster than reasoning.
3. **Read, don't guess.** Trace the actual values at runtime (logs, debugger, print). Confirm what each variable *actually is*, not what you assume. Most "impossible" bugs are a wrong assumption about state.
4. **Form one hypothesis.** State it explicitly: "I believe X is null because Y didn't run." Then design the single check that proves or disproves it.
5. **Fix the cause.** Once confirmed, fix the underlying fault, not the symptom. Patching the symptom leaves the fault latent.
6. **Add a regression test.** Lock the fix with a test that fails without it.

## Anti-patterns
- Changing multiple things at once. If the bug disappears you won't know which change did it.
- "Cleaning up" while debugging — it muddies the diff and hides the actual fix.