systematic-debugginglisted

# Systematic Debugging ## The Iron Law ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` Quick patches mask underlying issues. Systematic debugging is FASTER than thrashing. ## The Four Phases (Must Complete in Order) ### Phase 1: Root Cause Investigation (MANDATORY) 1. **Read Error Messages Carefully** — full stack traces, exact line numbers 2. **Reproduce Consistently** — if not reproducible, gather more data before proceeding 3. **Check Recent Changes** — git diff, recent commits, new dependencies 4. **Gather Evidence (Multi-Component Systems)** ``` For EACH component boundary: - Log what data enters the component - Log what data exits the component - Verify environment/config propagation Run once to gather evidence showing WHERE it breaks ``` 5. **Trace Data Flow** — where does the bad value originate? trace backward ### Phase 2: Pattern Analysis 1. Find working examples of similar code in the same codebase 2. Read reference implementations **completely** — don't skim 3. List every difference between working and broken 4. Understand all dependencies and assumptions ### Phase 3: Hypothesis and Testing 1. Form **one** specific hypothesis: "I think X is the root cause because Y" 2. Make the **smallest** possible change to test it 3. One variable at a time — never multiple changes simultaneously 4. Verify: works → Phase 4; doesn't work → form NEW hypothesis ### Phase 4: Implementation 1. Write a failing test case that reproduces the bug