| name | root-cause-analysis |
| description | Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or investigate why something is not working; especially for complex or intermittent issues across multiple components. Applies the Five Whys method, hypothesis-driven testing, stack trace analysis, git blame/log evidence gathering, and causal chain documentation to isolate and confirm root causes before applying any fix. |
| version | 1.0.0 |
| triggers | ["root cause","debugging","find the bug","why is this happening","investigate issue","bug investigation"] |
| tags | ["debugging","investigation","problem-solving","systematic"] |
| difficulty | intermediate |
| estimatedTime | 20 |
| relatedSkills | ["debugging/trace-and-isolate","debugging/hypothesis-testing"] |
Root Cause Analysis
You 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.
Core Principle
Never fix a symptom. Always find and fix the root cause.
The Five Whys Method
Ask "Why?" repeatedly to drill down to the root cause:
- Why did the API return an error? → The database query failed
- Why did the database query fail? → The connection pool was exhausted
- Why was the pool exhausted? → ROOT CAUSE: Missing
finally block to close connections
Investigation Phases
Phase 1: Reproduce the Bug
Before investigating:
- Reproduce consistently - If you can't reproduce it, you can't verify a fix
- Document reproduction steps - Exact sequence of actions
- Note environment details - OS, versions, configuration
- Identify minimal reproduction - Smallest case that shows the bug
Questions to answer:
- Does it happen every time or intermittently?
- Does it happen in all environments?
- When did it start happening? (recent changes)
Phase 2: Gather Evidence
Collect information before forming theories:
- Error messages and stack traces
- Log files (application, system, database)
- Recent code changes (git log, blame)
- User reports and reproduction steps
- Monitoring data (metrics, APM)
- Related issues (search issue tracker)
Do NOT:
- Make changes while gathering evidence
- Assume you know the cause without evidence
- Ignore related symptoms
Phase 3: Form Hypotheses
Based on evidence, create ranked hypotheses:
| Priority | Hypothesis | Evidence | Test Plan |
|---|
| 1 | Connection leak in UserService | Stack trace shows connection pool | Add logging, check usage |
| 2 | Query timeout too short | Occurs under load | Test with longer timeout |
| 3 | Database server overload |
