# Five Whys Root Cause Analysis > This skill should be used when the user reports "error", "bug", "problem", needs to "fix" something, mentions "debug", "failing", "broken", "issue", "not working", "crash", or any problem-solving scenario. Enforces systematic root cause identification using five whys methodology before attempting solutions. Use when this capability is needed. - Skill: `tomevault-io/five-whys-root-cause-analysis` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/five-whys-root-cause-analysis` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/five-whys-root-cause-analysis/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/five-whys-root-cause-analysis --- # Five Whys Root Cause Analysis ## Purpose This skill enforces systematic root cause identification before solution attempts. Apply the five whys methodology to prevent speculation-driven debugging that wastes effort, creates harmful changes, and results in never-ending fix loops. ## Core Problem Claude Code's default behavior when encountering problems: 1. Observe symptom 2. Speculate about cause 3. Implement speculative fix 4. Fix doesn't work or creates new problems 5. Repeat indefinitely **Result:** Wasted effort, potentially harmful changes, user frustration. ## Five Whys Methodology ### The Process Start with the observed symptom and iteratively ask "why?" until reaching an actionable root cause. **Example progression:** 1. **Symptom:** Login returns 500 error 2. **Why #1:** Why does login return 500? → Database connection timeout 3. **Why #2:** Why does database timeout? → Connection pool exhausted 4. **Why #3:** Why is pool exhausted? → Connections not being released 5. **Why #4:** Why aren't connections released? → Missing connection.release() call in session handler **Root cause identified:** Missing connection.release() call - this is actionable. ### Iteration Guidelines **Continue asking "why" until:** - The cause is **actionable** (can be fixed with code/config changes) - The cause **directly explains** the observed symptom - Next "why" would be **outside our control** (external system, architectural decision) **Don't stop at:** - Symptom restatements ("it's broken because it doesn't work") - Vague causes ("there's a configuration issue") - First plausible explanation without verification - Standard iteration counts (five is just a name - continue until root cause found) ### Evidence-Based Investigation **For each "why", gather evidence:** 1. **Read relevant code:** - Files mentioned in error messages - Call stack locations - Related modules and dependencies 2. **Examine outputs:** - Error messages and stack traces - Log files - Console output - Test results 3. **Check configurations:** - Environment variables - Config files - Build settings - Dependency versions 4. **Verify assumptions:** - Don't assume - check actual behavior - Read the code that's actually running - Check what values are actually present **Base each "why" answer on concrete evidence, not speculation.** ## Root Cause Determination ### Criteria for Root Cause A root cause is identified when ALL these conditions are met: 1. **Actionable:** - Can be fixed with code, configuration, or environment changes - Within our control to modify - Clear fix approach exists 2. **Directly Explanatory:** - Cause fully explains the observed symptom - No gaps in the causal chain - Removing this cause would eliminate the symptom 3. **Terminal:** - Next "why" would go outside our control (system architecture, external dependencies, business requirements) - OR: Next "why" would not lead to a more actionable fix - OR: This is the deepest layer we can address ### Example: Root Cause vs Symptom **Symptom:** "Tests are failing" - ❌ NOT root cause: "The test expectations are wrong" (what made them wrong?) - ❌ NOT root cause: "The code doesn't match tests" (why doesn't it match?) - ✅ ROOT CAUSE: "Function returns null when user.profile is undefined, but tests expect empty object" **Symptom:** "API returns 404" - ❌ NOT root cause: "Route doesn't exist" (why doesn't it exist?) - ❌ NOT root cause: "Router not configured" (what's the actual misconfiguration?) - ✅ ROOT CAUSE: "Route path is '/api/v1/users' but code defines '/api/users' - missing '/v1' prefix" ### When to Stop **Stop investigating when:** - Identified an actionable fix with clear implementation - Cause is a concrete code/config/data issue - Evidence confirms this cause produces the symptom **Continue investigating when:** - Cause is vague or speculative - No clear fix path exists - Haven't verified the cause with evidence - Fixing this wouldn't fully resolve symptom ## Anti-Patterns to Avoid ### Speculation Without Evidence ❌ **Bad:** ``` Why is login failing? → "Probably a timeout issue" [no evidence] → "Let me increase the timeout" [speculative fix] ``` ✅ **Good:** ``` Why is login failing? → [Read error logs] → Database connection timeout after 5 seconds → [Read database config] → Connection pool size is 5 → [Read application metrics] → 50 concurrent requests → Root cause: Connection pool too small for request volume ``` ### Stopping Too Early ❌ **Bad:** ``` Why are tests failing? → "Tests are outdated" → [Starts rewriting tests without understanding why they're outdated] ``` ✅ **Good:** ``` Why are tests failing? → Tests expect user.email, code returns user.emailAddress Why the field name difference? → API v2 migration changed field names Why weren't tests updated? → Tests live in separate repo, not updated in migration PR Root cause: Migration process doesn't include cross-repo test updates ``` ### Treating Symptoms ❌ **Bad:** ``` Error: "Cannot read property 'name' of undefined" → "Let me add null check" [treats symptom] ``` ✅ **Good:** ``` Why is object undefined? → API call returns undefined when user not found Why is API call made for non-existent user? → User ID comes from URL parameter without validation Why no validation? → Route handler assumes ID is always valid Root cause: Missing user ID validation in route handler ``` ## Progressive Output Format Show each investigation level as it completes: ```markdown ## Root Cause Analysis ### Investigation Level 1 **Observation:** [What was observed] **Evidence:** [What was checked - files, logs, outputs] **Finding:** [What this reveals] **Next Question:** Why [finding]? ### Investigation Level 2 **Observation:** [Deeper observation] **Evidence:** [More specific evidence] **Finding:** [What this reveals] **Next Question:** Why [finding]? [Continue until root cause identified] ### Root Cause Identified **Cause:** [Specific, actionable cause] **Evidence:** [Concrete evidence supporting this] **Fix Approach:** [How this can be addressed] **Why This is Root:** [Meets actionability, explanatory, and terminal criteria] ``` ## Integration with Problem Solving ### When Skill Activates This skill triggers automatically when: - User message contains problem keywords (error, bug, fix, debug, etc.) - Tool output contains errors or exceptions - User is clearly trying to solve a problem ### Agent Invocation When this skill triggers, it should invoke the root-cause-analyzer agent: - Agent runs autonomously through five whys - Shows progressive output for each iteration - Determines when root cause is reached - Completes automatically ### User Override User can bypass analysis by: - Interrupting the agent manually - Explicitly stating "skip root cause analysis" - Requesting immediate fix attempts **But default behavior is always root cause first.** ## Workflow 1. **Detect problem:** Skill triggers on keywords or errors 2. **Launch analysis:** Invoke root-cause-analyzer agent 3. **Autonomous iteration:** Agent works through whys without user prompts 4. **Progressive display:** Show each iteration as investigation proceeds 5. **Root cause identified:** Agent determines when criteria met 6. **Proceed to solution:** Now fix the identified root cause ## Success Criteria Root cause analysis is complete when: - ✅ Specific, actionable cause identified - ✅ Evidence gathered confirms the cause - ✅ Cause directly explains observed symptom - ✅ Clear fix approach exists - ✅ Fixing this cause will resolve the problem **Output statement:** "Root cause identified: [specific cause]. This is actionable and directly explains [symptom]. Proceeding to solution..." --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/tommymorgan) — claim your Tome and manage your conversions.