five-whys — Claude Code rule: what it does, how to install
The five-whys rule guides Claude Code through a five-question root-cause review. Use it when a visible failure needs a deeper process or system explanation.
MIT ★ 233 updated 2026-01-18
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineeringWhat five-whys does
five-whys gives Claude Code a four-part investigation flow: state the problem, ask why five times, validate the resulting root cause, then shape a remedy. The sequence links an observed symptom to deeper causes and asks whether fixing that cause would stop the issue from returning. It can also account for more than one root cause.
The rule directs the analysis toward processes and systemic conditions rather than individual blame. It also calls for documenting the reasoning, involving relevant stakeholders, and testing whether proposed fixes address the cause itself. That is the practical limit to watch: a chain of answers is not enough unless the proposed change would prevent recurrence.
After installation, the rule file is .claude/rules/five-whys.md. There is no dedicated slash command; ask Claude Code to investigate a problem using the Five Whys method.
What it helps with
- trace a failure back to its root cause
- separate an observed symptom from its cause
- validate a chain of causal answers
- design measures that prevent recurrence
- record a structured problem analysis
Example prompts for the agent
- Analyze this application failure with the Five Whys method, starting by stating the problem clearly.
- Check whether the proposed root cause explains the full chain and whether fixing it would prevent recurrence.
- Use
five-whysto investigate this issue and include possible systemic causes.
How to install five-whys
1Plugin marketplace
/plugin marketplace add johnrogers/claude-swift-engineering/plugin install swift-engineering@claude-swift-engineering2Manually: put the files in place
.claude/rules/five-whys.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/five-whys.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/five-whys.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/five-whys.mdManually: put the files in place
.clinerules/five-whys.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about five-whys
How do I install five-whys in Claude Code?
Run /plugin marketplace add johnrogers/claude-swift-engineering, then /plugin install swift-engineering@claude-swift-engineering. The rule file is .claude/rules/five-whys.md.
What does five-whys do?
It leads Claude Code through five successive why-questions, then checks the root cause and helps shape preventive measures.
How does the rule validate a root cause?
It checks the logic connecting each answer and asks whether addressing the root cause would prevent the problem from happening again. Multiple root causes can be considered when needed.
Source text
five-whys.md · MIT
## Five Whys Analysis Use the "Five Whys" root cause analysis technique to deeply understand problems. ### Process: #### 1. Define the Problem Clearly state the issue or symptom #### 2. Ask "Why?" Five Times - Why did this problem occur? → Answer 1 - Why did Answer 1 happen? → Answer 2 - Why did Answer 2 happen? → Answer 3 - Why did Answer 3 happen? → Answer 4 - Why did Answer 4 happen? → Answer 5 (Root Cause) #### 3. Validate Root Cause - Verify the logical chain - Check if addressing root cause prevents recurrence - Consider multiple root causes if applicable #### 4. Develop Solutions - Address the root cause, not just symptoms - Create preventive measures - Consider systemic improvements ### Example: **Problem**: Application crashes when processing large files 1. **Why?** → The application runs out of memory 2. **Why?** → It loads entire file into memory at once 3. **Why?** → The file parser wasn't designed for streaming 4. **Why?** → Initial requirements only specified small files 5. **Why?** → Requirements gathering didn't consider future growth **Root Cause**: Incomplete requirements gathering process **Solution**: Implement streaming parser and improve requirements process ### Best Practices: - Focus on process, not people - Look for systemic issues - Document the analysis - Involve relevant stakeholders - Test solutions address root cause
© John Rogers (@johnrogers) · MIT · johnrogers/claude-swift-engineering