systematic-debugginglisted

Find the root cause before you touch a line of code. A fix that targets a symptom you don't understand either fails or moves the bug somewhere else, and each blind attempt makes the next one harder to reason about. Investigation first is not the slow path — it is the fast one. ## The one rule **No fix before you can name the root cause.** If you can't say "the bug happens because X", you are still investigating, not fixing. The moment you feel "let me just try changing this and see" — stop. That instinct is the thing this skill exists to interrupt. This holds hardest exactly when it feels most skippable: under time pressure, when the bug "looks simple", when you've already tried two things. Simple bugs have root causes too, and guess-and-check is slower than it feels because every wrong attempt has to be unwound. ## Step 1: Investigate the root cause Do all of this before forming any fix. - **Read the actual error.** The full message, the full stack trace, line numbers, error codes. The answer is often already written there. Don't skim past it to the part you assume is the problem. - **Reproduce it reliably.** What exact steps trigger it? Every time, or intermittently? If you can't reproduce it, you can't confirm a fix — gather more data rather than guessing. - **Check what changed.** `git diff`, recent commits, new dependencies, config or environment differences. A bug that just appeared usually has a recent cause. - **Instrument the boundaries** when the system has mu