---

name: root-cause-analysis version: 1.0.0 description: This skill should be used when diagnosing failures, investigating incidents, finding root causes, or when "root cause", "diagnosis", "investigate", or "--rca" are mentioned.

Root Cause Analysis

Symptom → hypothesis formation → evidence gathering → elimination → root cause → verified fix.

<when_to_use>

• Diagnosing system failures or unexpected behavior
• Investigating incidents or outages
• Finding the actual cause vs surface symptoms
• Preventing recurrence through understanding
• Any situation where "why did this happen?" needs answering

NOT for: known issues with documented fixes, simple configuration errors, guessing without evidence

</when_to_use>

<discovery_phase>

Core Questions

Confidence Thresholds

At level 3+, transition to hypothesis formation. Below level 3, keep gathering context.

</discovery_phase>

<hypothesis_formation>

Quality Criteria

Multiple Working Hypotheses

Generate 2-4 competing theories:

1. List each hypothesis with supporting/contradicting evidence
2. Rank by likelihood (evidence support, parsimony, testability)
3. Design tests to differentiate between them

</hypothesis_formation>

<evidence_gathering>

Observation Collection

Breadcrumb Analysis

Trace backwards from symptom:

1. Last known good state — what was working?
2. First observable failure — when did it break?
3. Changes between — what's different?
4. Root trigger — first thing that went wrong

</evidence_gathering>

<hypothesis_testing>

Test Design

For each hypothesis:

1. Prediction — if true, what should we observe?
2. Test method — how to verify?
3. Expected result — what confirms/refutes?
4. Time budget — when to move on?

Testing Priorities

Execution Loop

Baseline → Single variable change → Observe → Document → Iterate

</hypothesis_testing>

<elimination_methodology>

Three core techniques:

See elimination-techniques.md for detailed methods.

</elimination_methodology>

<time_boxing>

If stuck beyond 2x estimate → step back, seek fresh perspective, or escalate.

</time_boxing>

<audit_trail>

Log every step:

Copy[TIME] PHASE: Action → Result
[10:15] DISCOVERY: Gathered error logs → Found NullPointerException
[10:22] HYPOTHESIS: User object not initialized
[10:28] TEST: Added null check logging → Confirmed user is null

Benefits: Prevents revisiting same ground, enables handoff, catches circular investigation.

See documentation-templates.md for full templates.

</audit_trail>

<common_pitfalls>

Watch for these patterns:

See pitfalls.md for detailed resistance patterns and recovery.

</common_pitfalls>

<confidence_calibration>

</confidence_calibration>

ALWAYS:

• Gather sufficient context before hypothesizing
• Form multiple competing hypotheses
• Test systematically, one variable at a time
• Document investigation trail
• Verify fix actually addresses root cause
• Document for future prevention

NEVER:

• Jump to solutions without diagnosis
• Trust single hypothesis without testing alternatives
• Apply fixes without understanding cause
• Skip verification of fix
• Repeat same failed investigation steps
• Hide uncertainty about root cause

Deep-dive documentation:

• elimination-techniques.md — binary search, variable isolation, process of elimination
• pitfalls.md — cognitive biases and resistance patterns
• documentation-templates.md — investigation logs and RCA reports

Related skills:

• debugging-and-diagnosis — code-specific debugging (loads this skill)
• codebase-analysis — uses for code investigation
• report-findings — presenting investigation results