runesleo/systematic-debugging

Systematic Debugging

Overview

Random fixes waste time and create new bugs.

Core principle: ALWAYS find root cause before attempting fixes.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
NO INVESTIGATION WITHOUT MEMORY RECALL FIRST

The Five Phases

Phase 0: Memory Recall (MANDATORY FIRST STEP)

1. Extract keywords from error (error type, component, project)
2. Query memory database for related past experiences
3. Review results:
   • Found relevant experience? → Apply directly, skip to Phase 4
   • Partial match? → Use as starting point
   • Nothing? → Proceed to Phase 1, remember to record solution later

Phase 1: Root Cause Investigation

1. Read error messages carefully — don't skip, read completely
2. Reproduce consistently — exact steps, every time?
3. Check recent changes — git diff, new deps, config changes
4. Gather evidence in multi-component systems — log at each component boundary, run once to find WHERE it breaks
5. Trace data flow — where does bad value originate? Trace backward to source

Phase 2: Pattern Analysis

1. Find working examples in same codebase
2. Compare against references — read completely, don't skim
3. Identify every difference between working and broken
4. Understand dependencies — settings, config, environment, assumptions

Phase 3: Hypothesis and Testing

1. Form single hypothesis: "I think X is the root cause because Y"
2. Test minimally — smallest possible change, one variable at a time
3. Verify before continuing — worked? → Phase 4. Didn't? → New hypothesis

Phase 4: Implementation

1. Create failing test case — simplest reproduction, automated if possible
2. Implement single fix — ONE change, no "while I'm here" improvements
3. Verify fix — test passes, no other tests broken
4. If 3+ fixes failed → STOP, question architecture, discuss before more attempts

Red Flags - STOP and Follow Process

• "Quick fix for now, investigate later"
• "Just try changing X"
• Proposing solutions before tracing data flow
• "One more fix attempt" (when already tried 2+)

ALL of these mean: STOP. Return to Phase 1.

Quick Reference

| Phase | Key Activities | Success Criteria | |-------|---------------|------------------| | 0. Memory Recall | Extract keywords, query memory | Output recall summary | | 1. Root Cause | Read errors, reproduce, gather evidence | Understand WHAT and WHY | | 2. Pattern | Find working examples, compare | Identify differences | | 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis | | 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |