root-cause-analysis

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:

1. Why did the API return an error? → The database query failed
2. Why did the database query fail? → The connection pool was exhausted
3. Why was the pool exhausted? → ROOT CAUSE: Missing finally block to close connections

Investigation Phases

Phase 1: Reproduce the Bug

Before investigating:

1. Reproduce consistently - If you can't reproduce it, you can't verify a fix
2. Document reproduction steps - Exact sequence of actions
3. Note environment details - OS, versions, configuration
4. 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