root-cause-analysis — Claude Code skill: trace failures to the cause
A skill that walks an incident down to the cause you can actually fix, instead of patching the symptom again.
npx skills add aj-geddes/useful-ai-prompts --skill root-cause-analysis -a claude-codeWhat root-cause-analysis does
root-cause-analysis gives the investigation a shape: symptom first, then a chain of why questions until you hit something actionable. The skill ships reference guides for the 5 Whys technique, a systematic RCA process, an incident report template, a set of analysis techniques, and a follow-up and prevention section. They live in the references/ directory.
Reach for it on production incidents, customer-facing breakage and problems that keep coming back. The documented example starts with a 503 and ends somewhere unexpected: the load testing environment never mirrored production data volume, so the real fix was an environment parity requirement rather than a missing index. That is the point of the exercise.
The skill does not gather evidence for you. Feed it logs, metrics and a timeline, or the why chain turns into guesswork and the report reads like one.
What it helps with
- trace a production incident to its actual cause
- stop a failure that keeps recurring after each fix
- write up an incident report from a ready template
- separate the cause of a failure from everything around it
- record prevention steps after the investigation closes
Example prompts for the agent
- Run a root cause analysis on this incident: the site returned 503 for half an hour, logs and timeline attached
- Work through 5 Whys on why the database connection pool kept exhausting, then suggest prevention
- Draft an RCA report for yesterday's failed deploy using the template
How to install root-cause-analysis
1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill root-cause-analysis -a claude-code2Manually: put the files in place
~/.claude/skills/root-cause-analysis/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/root-cause-analysis/
1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill root-cause-analysis -a codex2Manually: put the files in place
.agents/skills/root-cause-analysis/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill root-cause-analysis -a cursor2Manually: put the files in place
.cursor/skills/root-cause-analysis/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install aj-geddes/useful-ai-prompts root-cause-analysis2Manually: put the files in place
.github/skills/root-cause-analysis/SKILL.md1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill root-cause-analysis -a gemini-cli2Platform CLI
gemini skills install https://github.com/aj-geddes/useful-ai-prompts --path skills/root-cause-analysisManually: put the files in place
.devin/skills/root-cause-analysis/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill root-cause-analysis -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about root-cause-analysis
How do I install root-cause-analysis in Claude?
Run npx skills add aj-geddes/useful-ai-prompts --skill root-cause-analysis -a claude-code. The skill lands at ~/.claude/skills/root-cause-analysis/SKILL.md.
What does root-cause-analysis do?
It structures failure analysis: a chain of why questions, RCA techniques, a report template and a prevention section for recurring issues.
What do I need before running it?
Incident facts: logs, metrics, a timeline. The skill does not collect them itself, it builds the analysis on what you provide.
Source text
SKILL.md · MIT
--- name: root-cause-analysis description: > Conduct systematic root cause analysis to identify underlying problems. Use structured methodologies to prevent recurring issues and drive improvements. --- # Root Cause Analysis ## Table of Contents - [Overview](#overview) - [When to Use](#when-to-use) - [Quick Start](#quick-start) - [Reference Guides](#reference-guides) - [Best Practices](#best-practices) ## Overview Root cause analysis (RCA) identifies underlying reasons for failures, enabling permanent solutions rather than temporary fixes. ## When to Use - Production incidents - Customer-impacting issues - Repeated problems - Unexpected failures - Performance degradation ## Quick Start Minimal working example: ```yaml Example: Website Down Symptom: Website returned 503 Service Unavailable Why 1: Why was website down? Answer: Database connection pool exhausted Why 2: Why was connection pool exhausted? Answer: Queries taking too long, connections not released Why 3: Why were queries slow? Answer: Missing index on frequently queried column Why 4: Why was index missing? Answer: Performance testing didn't use production-like data volume Why 5: Why wasn't production-like data used? Answer: Load testing environment doesn't mirror production Root Cause: Load testing environment under-provisioned Solution: Update load testing environment with production-like data Prevention: Establish environment parity requirements ``` ## Reference Guides Detailed implementations in the `references/` directory: | Guide | Contents | |---|---| | [The 5 Whys Technique](references/the-5-whys-technique.md) | The 5 Whys Technique | | [Systematic RCA Process](references/systematic-rca-process.md) | Systematic RCA Process | | [RCA Report Template](references/rca-report-template.md) | RCA Report Template | | [Root Cause Analysis Techniques](references/root-cause-analysis-techniques.md) | Root Cause Analysis Techniques | | [Follow-Up & Prevention](references/follow-up-prevention.md) | Follow-Up & Prevention | ## Best Practices ### ✅ DO - Follow established patterns and conventions - Write clean, maintainable code - Add appropriate documentation - Test thoroughly before deploying ### ❌ DON'T - Skip testing or validation - Ignore error handling - Hard-code configuration values
© aj-geddes · MIT · aj-geddes/useful-ai-prompts
