systematic-debugginglisted

# Systematic Debugging Use this skill when something is broken and the cause is not yet proven. ## Core Principle Do not jump to fixes before understanding the root cause. Symptom-first fixes waste time, hide the real problem, and often create follow-up bugs. ## When to Use This Skill Use this skill for: - failing tests - runtime bugs - build or CI failures - flaky behavior - integration issues - performance regressions with unclear cause Use it especially when: - the issue seems deceptively simple - you are under time pressure - you already tried one or two fixes - the failure spans multiple components or layers ## The Rule No fix before root-cause investigation. If you have not yet reproduced the issue, collected evidence, and formed a concrete hypothesis, you are not ready to implement a fix. ## The Four Phases ### 1. Root-Cause Investigation Before changing code: - read the error message and stack trace carefully - reproduce the issue consistently if possible - identify what recently changed - gather evidence at the component boundaries where things may be breaking - trace bad values or bad state backward toward the source If the issue appears deep in a call chain, read `root-cause-tracing.md` in this skill. If the issue involves multiple layers, add targeted instrumentation so you can see where the breakdown begins. ### 2. Pattern Analysis Before fixing: - find a similar working example in the codebase - compare working and broken behavior carefully