systematic-debugging

1# Systematic Debugging
2 
3## Overview
4 
5**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
6 
7**Violating the letter of this process is violating the spirit of debugging.**
8 
9## The Iron Law
10 
11```
12NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
13```
14 
15If you haven't completed Phase 1, you cannot propose fixes.
16 
17## When to Use
18 
19Use for ANY technical issue:
20- Test failures
21- Bugs in production
22- Unexpected behavior
23- Performance problems
24- Build failures
25- Integration issues
26 
27**Use this ESPECIALLY when:**
28- Under time pressure (emergencies make guessing tempting)
29- "Just one quick fix" seems obvious
30- You've already tried multiple fixes
31- Previous fix didn't work
32- You don't fully understand the issue
33 
34**Don't skip when:**
35- Issue seems simple (simple bugs have root causes too)
36- You're in a hurry (rushing guarantees rework)
37- Manager wants it fixed NOW (systematic is faster than thrashing)
38 
39## The Four Phases
40 
41You MUST complete each phase before proceeding to the next.
42 
43### Phase 1: Root Cause Investigation
44 
45**BEFORE attempting ANY fix:**
46 
471. **Read Error Messages Carefully**
48   - Don't skip past errors or warnings
49   - They often contain the exact solution
50   - Read stack traces completely
51   - Note line numbers, file paths, error codes
52 
532. **Reproduce Consistently**
54   - Can you trigger it reliably?
55   - What are the exact steps?
56   - Does it happen every time?
57   - If not reproducible → gather more data, don't guess
58…