Systematic root cause analysis using lean methods (5 Whys, Ishikawa, Gemba). Use when encountering unexpected behavior, errors, or defects to find and fix the true root cause rather than symptoms.
Systematically identify and fix the root cause of defects using lean methods. Stop fixing symptoms — find the true cause.
When to use: Unexpected behavior, unclear test failures, integration issues, performance problems, bug fix stories.
When to skip: Obvious typos, simple syntax errors — go directly to fix.
Inputs: Problem statement, steps to reproduce, error messages/symptoms. Time boxing: XS (5 min), S (15 min), M (30 min), L (60 min). Escalate if exceeded.
<verification> Tier declared. Method selected. </verification> <verification> Problem is specific and reproducible (or minimal fixture built). </verification> <if-blocked> Cannot reproduce → gather logs, add instrumentation, build minimal fixture. </if-blocked> <verification> Root cause is actionable and explains all symptoms. </verification> <if-blocked> Chain branches → switch to Ishikawa (Step 2b). </if-blocked> <verification> Root cause confirmed with evidence. Competing hypotheses eliminated. </verification> <verification> Problem resolved. Tests pass. </verification> <if-blocked> Fix incomplete → document partial fix, create follow-up task. </if-blocked>Before choosing a method, classify the bug:
| Tier | Criteria | Method | Output |
|---|---|---|---|
| XS | Cause evident, fix obvious | Skip to Step 3 | One-liner in scope/commit |
| S | Cause obscure, single causal chain | 5 Whys (Step 2) | Summary block |
| M/L | Multiple possible causes | Ishikawa (Step 2b) | analysis.md |
State the tier explicitly before proceeding.
Go see the actual problem. Reproduce it, capture evidence:
WHAT: [specific behavior observed]
WHEN: [conditions / triggers]
WHERE: [file:line or component]
EXPECTED: [what should happen instead]
Ask "Why?" five times, staying on one factual causal chain:
Problem: [statement]
1. Why? → [first-level cause, with evidence]
2. Why? → [second-level cause]
3. Why? → [third-level cause]
4. Why? → [fourth-level cause]
5. Why? → [root cause]
Countermeasure: [fix]
Rules:
Explore 6 M's: Method, Machine, Material, Measurement, Manpower, Milieu (env/config drift).
Identify top 2-3 hypotheses, investigate systematically:
| Hypothesis | Test | Result | Conclusion |
|---|---|---|---|
| [Cause 1] | [How tested] | [What happened] | Confirmed/Eliminated |
Fix the root cause (not symptoms). Write the regression test first (RED), then fix (GREEN).
Prevention (choose what applies):
rai pattern add for recurring systemic issuesFeed /rai-story-plan — after fixing, name the tasks explicitly:
rai pattern add "[statement]" --context "[keywords]" --type behavioral| Tier | Artifact | Destination |
|---|---|---|
| XS | One-liner root cause + fix | Scope commit or inline |
| S | Summary block (root cause, fix, prevention) | Story scope doc |
| M/L | Full analysis | work/debug/{issue-name}/analysis.md |
| Any | Story plan tasks | Fed to /rai-story-plan |