systematic-debugging

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