systematic-debugginglisted

# Systematic Debugging ## Overview Random fixes waste time and create new bugs. Quick patches mask the underlying issue and it resurfaces later. **Core principle:** find the root cause before attempting a fix, always. A fix that only addresses the symptom is not a fix. Find the root cause before you change any code. ## When to Use Any technical issue: test failures, production bugs, unexpected behavior, performance, build or integration problems. It matters most exactly when it feels least convenient: under time pressure, when one quick fix looks obvious, or after previous fixes have already failed. Simple bugs still have root causes, and systematic is faster than thrashing. ## The Four Phases Complete each phase before moving to the next. ### Phase 1: Root Cause Investigation Goal: understand what is failing and why, backed by evidence. - Read repository instructions (they govern process), canonical `CONTEXT.md` if present (current domain vocabulary), relevant accepted ADRs when present (narrower design intent), and matching project memories when present (hidden historical hints: reverify before use). Surface conflicts; never silently resolve one. - Read error output completely. Messages, stack traces, and line numbers often name the cause. - Reproduce reliably. If you cannot, gather more data rather than guess. - Actual observed behavior is authoritative for diagnosis. Complete the diagnosis before planning a change; documents describe intended state but