root-cause-debugginglisted

# Root-Cause Debugging No fix until you can state the root cause and point to the evidence for it. Fixing symptoms wastes time and breeds new bugs. ## Investigate first 1. Read the complete error message and stack trace — they often contain the answer. 2. Reproduce reliably. If you can't reproduce, gather more data instead of guessing. 3. Check what changed: recent commits, dependency updates, config, environment. 4. Trace bad values upstream to where they originate. Fix at the source, not where it crashed. ## Multi-component systems (API → service → DB, CI → build → deploy) Don't guess which layer is broken. Add logging at each component boundary (what enters, what exits, whether env/config propagates), run once, and read the evidence to locate the failing layer. Then investigate only that layer. ## Hypothesis discipline - One hypothesis at a time: "I think X is the cause because Y." - Test it with the smallest possible change. Never stack multiple fixes in one attempt. - Failed? Form a new hypothesis from the new evidence — don't pile another fix on top. ## Stop rules - **3 failed fixes → stop.** Especially when each fix reveals a new problem somewhere else — that pattern means the architecture is wrong, not the code. Discuss before attempting fix #4. - Catch yourself thinking "just try X and see" or "it's probably X, let me fix it" → return to investigation. ## Landing the fix Write a test that reproduces the bug: it must fail before your fix and pass after. If