Skip to main content
rule CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineering
Open on GitHub

What 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-whys to 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-engineering

2Manually: put the files in place

.claude/rules/five-whys.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Code review and refactoring →

From the same set33

The whole set →
swift-style swift-style — a skill for Claude Code, Codex, Cursor and other AI coding platforms that enforces Swift code style: naming, spacing, section order, guard patterns. Applied automatically when working with .swift files. CX Codex +1 1,500installs restore-snapshot The restore-snapshot command uses .claude/snapshot.md to recap prior work and ask what to tackle next. Run it when you want to carry context into a new session. CX Codex +1 ★ 233repo stars snapshot Captures what you've accomplished and writes a summary to .claude/snapshot.md. Use it to quickly restore context in the next session via the resume-snapshot command. CX Codex +1 ★ 233repo stars generating-swift-package-docs generating-swift-package-docs generates on-demand Swift package documentation from DerivedData when inspecting unfamiliar module imports. CX Codex +1 ★ 233repo stars swift-test-creator swift-test-creator writes unit and integration tests with Swift Testing — @Test, #expect, #require. Meant to run once the feature code is in place. CX Codex ★ 233repo stars swift-documenter swift-documenter is a Claude Code subagent that creates and updates README files and Swift doc comments after a feature is finished or during package documentation revisions. CX Codex ★ 233repo stars swift-modernizer The swift-modernizer subagent updates legacy Swift code toward async/await, modern APIs, and SwiftUI. Use it to plan and verify incremental migrations in an existing project. CX Codex ★ 233repo stars reflect reflect is a Claude Code command that reviews chat context and project settings, then suggests changes to instructions, commands, and configuration. CX Codex +1 ★ 233repo stars

Project sponsors

Companies that keep this analytics open