systematic-debugginglisted

# Systematic Debugging ## Overview Random fixes waste time and create new bugs. Quick patches mask the underlying issue. **Core principle:** always find the root cause before attempting a fix. Symptom fixes are failure. ## The iron law ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` **Especially when:** under time pressure, "just one quick fix" seems obvious, you've already tried multiple fixes, or you don't fully understand the issue yet. None of these are reasons to skip investigation — they're exactly when guessing gets expensive. ## The four phases ### Phase 1: Root cause investigation 1. **Read error messages and stack traces completely** — line numbers, file paths, error codes, not just the first line. 2. **Reproduce consistently** — exact steps, every time. Not reproducible? Gather more data, don't guess. 3. **Check recent changes** — git diff, recent commits, new dependencies, config or environment differences. 4. **In multi-component systems, gather evidence at each boundary** before proposing fixes: log what enters/exits each component, verify config/env propagation, check state at each layer. Run once, see *where* it breaks, then investigate that specific component. 5. **Trace data backward** when the error is deep in a call stack: where did the bad value originate? What called this with that bad value? Keep tracing up to the source — fix at the source, not at the symptom. ### Phase 2: Pattern analysis - Find working examp