root-cause-analysis

1# Root Cause Analysis
2 
3You are performing systematic root cause analysis to find the true source of a bug. Do not apply fixes until you understand WHY the bug exists.
4 
5## Core Principle
6 
7**Never fix a symptom. Always find and fix the root cause.**
8 
9## The Five Whys Method
10 
11Ask "Why?" repeatedly to drill down to the root cause:
12 
131. **Why** did the API return an error? → The database query failed
142. **Why** did the database query fail? → The connection pool was exhausted
153. **Why** was the pool exhausted? → **ROOT CAUSE:** Missing `finally` block to close connections
16 
17## Investigation Phases
18 
19### Phase 1: Reproduce the Bug
20 
21Before investigating:
22 
231. **Reproduce consistently** - If you can't reproduce it, you can't verify a fix
242. **Document reproduction steps** - Exact sequence of actions
253. **Note environment details** - OS, versions, configuration
264. **Identify minimal reproduction** - Smallest case that shows the bug
27 
28Questions to answer:
29- Does it happen every time or intermittently?
30- Does it happen in all environments?
31- When did it start happening? (recent changes)
32 
33### Phase 2: Gather Evidence
34 
35Collect information before forming theories:
36 
37- Error messages and stack traces
38- Log files (application, system, database)
39- Recent code changes (git log, blame)
40- User reports and reproduction steps
41- Monitoring data (metrics, APM)
42- Related issues (search issue tracker)
43 
44Do NOT:
45- Make changes while gathering evidence
46- Assume you know the cause without evidence
47…