A Claude code command that seeks the root cause of a problem when using Claude code, and suggests corrective action

five-whys.md

Five Whys Root Cause Analysis

After a defect or problem has been fixed, use this command to find the root cause and prevent recurrence.

Process

1. Ask me to describe the defect or problem that occurred
2. Ask "Why did this happen?" and wait for my response
3. Based on my answer, ask "Why?" again, probing deeper
4. Continue until we reach a root cause (typically 3-6 iterations) - stop when we hit something systemic rather than symptomatic
5. Summarise the causal chain we've uncovered

Root Cause Categories

Classify the root cause as one of:

• Knowledge gap - something wasn't known or documented
• Missing guard - a test, assertion, or check that should exist
• Process friction - a manual step that's easy to forget or skip
• Unclear context - Claude Code or future-me lacks necessary background
• Tooling gap - a repeatable task that deserves automation
• Behaviour change - a practice or habit to adopt or avoid

Action

Based on the category, propose ONE concrete change:

• Knowledge gap → propose an addition to CLAUDE.md
• Missing guard → propose a specific test or check to add
• Process friction → propose a new or updated custom command
• Unclear context → propose an addition to CLAUDE.md
• Tooling gap → propose a new custom command
• Behaviour change → generate a markdown file titled practice-note-YYYY-MM-DD-<slug>.md suitable for project notes or PKM

Present the proposed change as a diff or complete file content that I can accept, modify, or reject.

Keep the focus on systemic improvement, not individual blame.

Practice Note Structure

When generating a behaviour change practice note, use this format:

# <Brief title describing the practice>

Tags: #<tag1> #<tag2>

## Context

What situation or trigger makes this practice relevant?

## The Insight

What did we learn from the Five Whys analysis? Include the causal chain briefly.

## The Practice

A clear, actionable statement of what to do (or stop doing). Frame positively where possible.

## Example

A concrete example from the incident that prompted this note.

---
*Generated: YYYY-MM-DD*
*Source: Five Whys analysis of <brief problem description>*

Keep practice notes short - ideally one screen. They should be scannable reminders, not essays.

Suggest 1-3 tags from areas like: #testing, #workflow, #design, #communication, #tooling, #debugging, #review, #documentation - or propose a new tag if none fit well.