systematic-debugginglisted

# Systematic Debugging ## Purpose Find and verify the **cause** of a failure rather than iterating through plausible patches until the symptom disappears. The method is evidence-driven and repository-aware. It should reduce uncertainty on every meaningful step. ## When to use Use this capability when: - a test, build, runtime flow, integration, or production-like behavior fails for an unclear reason; - a defect is intermittent or crosses multiple layers; - a previous fix treated a symptom but the problem persists; - there are several plausible causes and editing immediately would confound the diagnosis. For an obvious local defect whose cause is already proven by direct evidence, fix it and verify it rather than producing a debugging ceremony. ## Core principles ### Separate observation from explanation A stack trace, failing assertion, log line, changed value, request payload, or timing measurement is an observation. “Probably a race condition” is a hypothesis until evidence discriminates it from alternatives. ### Change one causal variable at a time where practical Experiments should distinguish hypotheses. Multiple simultaneous speculative edits destroy information even when they accidentally make the symptom disappear. ### Debug the narrowest real path Start at the observed failure and trace backward/forward through the actual data/control path. Do not scan unrelated code merely because it uses the same technology. ### A disappearing symptom is not automat