Find root cause using 5 Whys, Ishikawa, Gemba. Use when encountering errors or defects.
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 process| 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 |