debuglisted

# Debug — Systematic Debugging ## Iron Law NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Symptom fixes are whack-a-mole debugging. ## Process ### 0. Recall - Query the knowledge graph: `epic mem search "ERROR_MESSAGE_OR_FILE"` for the error message or file name - Check if a `resolution` or `pattern` node exists for this error category - If a past resolution exists, apply it directly instead of re-debugging from scratch **Why**: Past resolutions save 10-30 minutes of re-investigation. The knowledge graph exists so you don't repeat work. ### 1. Observe - Read the full error message and stack trace - Identify: What was expected? What actually happened? - Note the exact file, line, and function **Why**: Precise observation prevents misdiagnosis. Most debug loops start from skimming the error instead of reading it fully. ### 2. Hypothesize Form 2-3 possible causes. Rank by likelihood. **Why**: Ranked hypotheses prevent random code changes. Even a wrong hypothesis narrows the search space. ### 3. Isolate - **Narrow the scope**: Binary search through recent changes - **Reproduce minimally**: Smallest input that triggers the error - **Check assumptions**: Print/log intermediate values - **Bisect**: `git log --oneline -10` — when did it last work? **Why**: Isolation proves the cause before you touch any code. Without it, you're guessing. ### 4. Fix - Fix the root cause, not the symptom - If the fix is a workaround, add a TODO with explanation **Why**: Root cause fixes