systematic-debugginglisted

# Systematic Debugging ## The Iron Law ``` NO FIX WITHOUT ROOT-CAUSE INVESTIGATION FIRST ``` A fix proposed before Phase 1 is complete is a guess, not a fix. Guesses that happen to work are indistinguishable from guesses that don't until the bug resurfaces somewhere else. ## When to use Any technical issue: a failing test, a production bug, unexpected output, a performance regression, a build failure, an integration that doesn't behave as documented. **Especially** when under time pressure, when "just one quick change" seems obvious, or when a previous fix attempt didn't work — those are exactly the conditions where guessing feels fastest and costs the most. **Don't skip because the bug looks simple.** Simple bugs have root causes too, and finding one usually takes minutes, not hours. ## Phase 1: Root-cause investigation Before touching any code: 1. **Read the actual error.** Full stack trace, not the first line. Note exact file paths, line numbers, and error codes — they often name the fix directly. 2. **Reproduce it.** Confirm exact, repeatable steps. If it won't reproduce reliably, that's information — gather more data (logging, a tighter repro case) rather than guessing at a fix for a moving target. 3. **Check recent changes.** `git log`/`git diff` on the affected paths, recent dependency bumps, config or environment drift. Most bugs are introduced by something that changed, not something that was always broken. 4. **Trace the data flow back