debuglisted

# Systematic Debugging ## The Iron Law ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` If you haven't completed Phase 1, you cannot propose fixes. **Violating the letter of this process is violating the spirit of debugging.** ## The Four Phases You MUST complete each phase before proceeding to the next. ### Phase 1: Root Cause Investigation **BEFORE attempting ANY fix:** 1. **Read error messages carefully** - Don't skip past errors or warnings - Read stack traces completely - Note line numbers, file paths, error codes 2. **Reproduce consistently** - Can you trigger it reliably? What are the exact steps? - If not reproducible → gather more data, don't guess 3. **Check recent changes** - Git diff, recent commits, new dependencies, config changes - Environmental differences 4. **Gather evidence in multi-component systems** For EACH component boundary: - Log what data enters component - Log what data exits component - Verify environment/config propagation Run once to gather evidence showing WHERE it breaks, THEN analyze. 5. **Trace data flow** - Where does bad value originate? - What called this with bad value? - Keep tracing up until you find the source - Fix at source, not at symptom ### Phase 2: Pattern Analysis 1. **Find working examples** in same codebase 2. **Compare against references** — read reference implementation COMPLETELY (don't skim) 3. **Identify ALL differences** between working and broken 4.