root-cause-analysis

🔬 Root Cause Analysis Skill

Philosophy: Don't stop at the first "why" — dig until you hit bedrock.

When to Use

Use this skill when:

• Systematic debugging found the bug but not WHY it exists
• Issue keeps recurring despite fixes
• Bug seems to have multiple contributing factors
• You need to prevent similar bugs in the future
• There's a systemic/architectural issue suspected

Do NOT use this skill when:

• Bug is simple and obvious
• Time is extremely limited (use quick-fix)
• Just need to patch, not understand

Prerequisites

Before starting:

• Bug has been identified (what is happening)
• Have access to relevant code and history
• Understand the system architecture (high level)
• Have time for thorough analysis (~30-60 mins)

Process

Phase 1: PROBLEM DEFINITION 📝

Goal: Clearly define what we're analyzing.

Steps:

1. State the Problem Precisely

   Template:
   "When [condition], the system [actual behavior] 
    instead of [expected behavior]."
   
   Example:
   "When a user submits a login form with special characters,
    the system returns a 500 error instead of validating input."
   

2. Gather Impact Data

   • How often does it occur?
   • Who/what is affected?
   • What's the business impact?
   • How long has it been happening?

3. Document Timeline

   • When did it first appear?
   • Any recent changes before first occurrence?
   • Has it gotten better/worse?

Output: Clear problem statement with context.

Phase 2: THE 5 WHYS ANALYSIS 🔍

Goal: Drill down to fundamental causes.

Method:

Start: Problem Statement
  │
  ├─ Why? → First-level cause
  │   │
  │   ├─ Why? → Second-level cause
  │   │   │
  │   │   ├─ Why? → Third-level cause
  │   │   │   │
  │   │   │   ├─ Why? → Fourth-level cause
  │   │   │   │   │
  │   │   │   │   └─ Why? → ROOT CAUSE

Rules:

1. Each answer must be factual, not speculative
2. If multiple answers possible at a level, branch and explore all
3. Stop when you reach something actionable
4. "Human error" is NEVER a root cause — dig deeper

Example:

Problem: Login fails with special characters

Why #1: Server returns 500 error
  → Because: Unhandled exception in auth.service.ts

Why #2: Why is there an unhandled exception?
  → Because: SQL query fails with syntax error

Why #3: Why does SQL have syntax error?
  → Because: User input is concatenated directly into query

Why #4: Why is input concatenated directly?
  → Because: Developer didn't use parameterized queries

Why #5: Why didn't developer use parameterized queries?
  → Because: No code review caught it, and no security guidelines exist

ROOT CAUSE: Missing security coding standards and review process

Phase 3: FISHBONE DIAGRAM (ISHIKAWA) 📊

Goal: Explore contributing factors systematically.

Categories to Examine:

                              ┌──────────┐
          ┌──────────────────►│          │
          │    Environment    │          │
          │                   │          │
┌─────────┴───┐               │  PROBLEM │
│   Methods   ├──────────────►│          │
└─────────────┘               │          │
                              │          │
┌─────────────┐               │          │
│  Machines   ├──────────────►│          │
│  (Systems)  │               │          │
└─────────────┘               └─────┬────┘
                                    │
         ┌───────────────────────────┘
         │
    ┌────┴────┐    ┌──────────┐    ┌──────────┐
    │ People  │    │Materials │    │Measurement│
    │(Process)│    │  (Data)  │    │ (Metrics)│
    └─────────┘    └──────────┘    └──────────┘

For Each Category, Ask:

Phase 4: CONTRIBUTING FACTOR ANALYSIS 🧩

Goal: Weight and prioritize contributing factors.

Steps:

1. List All Contributing Factors Combine findings from 5 Whys and Fishbone

2. Score Each Factor

   scoring:
     frequency: 1-5 (how often does this contribute?)
     detectability: 1-5 (how hard to detect? 5=very hidden)
     severity: 1-5 (how much impact when it contributes?)
     
     risk_score: frequency × detectability × severity
   

3. Create Priority Matrix

   High Frequency + High Severity → Address immediately
   High Frequency + Low Severity → Address soon
   Low Frequency + High Severity → Create safeguards
   Low Frequency + Low Severity → Monitor only
   

Phase 5: ROOT CAUSE VALIDATION ✅

Goal: Confirm the root cause is correct.

Validation Questions:

1. Causation Test

   • If we fix this, will the problem definitely not recur?
   • Can we prove cause → effect relationship?

2. Completeness Test

   • Are there other causes we might have missed?
   • Would fixing this alone be sufficient?

3. Actionability Test

   • Can we actually address this cause?
   • Is it within our control?

4. Proportionality Test

   • Is the root cause proportional to the problem?
   • (Big problems usually have big root causes)

Phase 6: PREVENTION RECOMMENDATIONS 🛡️

Goal: Prevent recurrence.

Recommendation Types:

1. Immediate Fix

   • Direct fix for the symptom
   • Buys time for proper solution

2. Root Cause Fix

   • Addresses the fundamental cause
   • Prevents this exact issue

3. Systemic Improvement

   • Prevents entire class of similar issues
   • Usually involves process/tooling changes

4. Detection Improvement

   • Catch similar issues earlier next time
   • Monitoring, testing, review improvements

Example Recommendations:

for_the_sql_injection_example:
  immediate:
    - Fix the specific query to use parameters
    - Add input sanitization
  
  root_cause:
    - Establish secure coding guidelines
    - Require security review for auth code
  
  systemic:
    - Enable SQL injection detection in SAST tooling
    - Add security-focused code review checklist
    - Security training for developers
  
  detection:
    - Add SQL injection tests to CI pipeline
    - Monitor for unusual database queries

Output Template

# Root Cause Analysis Report

## Problem Statement
[Clear statement of the problem]

## Timeline
- First observed: [date]
- Recent changes: [list]
- Frequency: [how often]

## 5 Whys Analysis
1. Why? → [answer]
2. Why? → [answer]
3. Why? → [answer]
4. Why? → [answer]
5. Why? → [answer]

## Contributing Factors
| Factor | Category | Risk Score | Priority |
|--------|----------|------------|----------|
| [factor] | [cat] | [score] | [priority] |

## Root Cause
[Clear statement of root cause]

## Validation
- [ ] Causation confirmed
- [ ] Complete (no other causes)
- [ ] Actionable
- [ ] Proportional

## Recommendations
### Immediate
- [action]

### Root Cause Fix
- [action]

### Systemic
- [action]

### Detection
- [action]

Guidelines

DO ✅

• Follow the evidence, not assumptions
• Keep asking "why" until you can't anymore
• Document everything for future reference
• Involve domain experts when needed
• Look for patterns across similar issues

DON'T ❌

• Blame individuals (focus on systems)
• Stop at the first plausible answer
• Skip validation steps
• Propose fixes before understanding cause
• Ignore contributing factors

Success Criteria

Before claiming analysis complete:

• Problem clearly defined with impact
• 5 Whys completed to true root cause
• Contributing factors identified and scored
• Root cause validated against all tests
• Prevention recommendations at all levels
• Report documented for future reference

Related Skills

• skills/kilo-kit/debugging/systematic/ - For initial bug identification
• skills/kilo-kit/debugging/verification/ - For validating fixes
• skills/kilo-kit/quality/code-review/ - For review improvements

Root Cause Analysis Skill v1.0.0 — Dig until you hit bedrock