systematic-debugginglisted

# Systematic debugging Use when facing: test failures, production bugs, unexpected behaviour, performance problems, build failures, integration issues. Especially critical under time pressure, when a "quick fix" seems obvious, after multiple failed attempts, or when understanding is incomplete. ## The Iron Law **No fixes without root cause investigation first.** A symptom fix creates a whack-a-mole loop. The symptom disappears; the actual cause moves somewhere else; the next bug is harder to find because the original mechanism is now partially masked. Investigation is not optional. Even under deadline. ## Phase 1 — Root cause investigation Before proposing any fix, complete these steps in order: ### Read the error message carefully Stack traces, line numbers, file paths. The message is usually telling the truth about what happened, even when it's misleading about why. Read every line. Don't pattern-match the top line and skip the rest. ### Reproduce reliably Can you trigger the bug on demand? What are the exact steps? If you can't reproduce, you're debugging the wrong thing — or the bug is timing-dependent and needs a different investigation approach. ### Track what changed `git log`. `git diff` against the last known-good point. Check dependencies (`pnpm-lock.yaml`, `package.json`), configuration (`.env`, `turbo.json`, `tsconfig.*`), environmental differences (Node version, OS). Recent changes are the first-order suspects. ### Log at component boundaries For b