Root Cause Analysis
- 657 installs
- 305 repo stars
- Updated March 4, 2026
- aj-geddes/useful-ai-prompts
root-cause-analysis is a Claude Code skill that produces structured incident RCAs with timelines, 5 Whys, prioritized fixes, and follow-up prevention for developers who need postmortems beyond quick hotfix notes.
About
root-cause-analysis is an incident postmortem skill from aj-geddes/useful-ai-prompts that walks developers through timeline reconstruction, log and metrics review, 5 Whys root-cause identification, contributing-factor analysis, and follow-up prevention checklists. The skill outputs action items with owners and deadlines, plus monitoring, testing, and procedural changes to stop recurrence. Use it when an outage or regression needs a documented RCA with shareable learnings rather than a Slack thread or one-line fix summary. The bundled checklist covers incident documentation, timeline establishment, log review, metrics analysis, and preventive measure tracking.
- End-to-end RCA checklist from documentation through debrief and assigned action items
- 5 Whys and contributing-factors framing with example incident timeline and impact block
- Follow-up loop: owners, deadlines, retros, and effectiveness monitoring
- Prevention bundle: tests, alerts, procedures, and training hooks
- RCA report template with severity, duration, and revenue-style impact fields
Root Cause Analysis by the numbers
- 657 all-time installs (skills.sh)
- Ranked #67 of 596 Debugging skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill root-cause-analysisAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 657 |
|---|---|
| repo stars | ★ 305 |
| Security audit | 3 / 3 scanners passed |
| Last updated | March 4, 2026 |
| Repository | aj-geddes/useful-ai-prompts ↗ |
How do you write a structured incident RCA?
Install this skill when an incident needs a structured RCA with timeline, 5 Whys, prioritized fixes, and follow-up prevention—not a quick hotfix note.
Who is it for?
Engineers and SREs documenting production incidents who need a repeatable RCA format with owners and follow-ups.
Skip if: Developers who only need a quick local bug fix without incident documentation or team-wide follow-up.
When should I use this skill?
An incident needs structured RCA with timeline, 5 Whys, prioritized fixes, and follow-up prevention—not a quick hotfix note.
What you get
Incident timeline, 5 Whys analysis, prioritized action items, prevention checklist, and shared learnings document
- RCA document
- Action item list
- Prevention checklist
Files
Root Cause Analysis
Table of Contents
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:
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 requirementsReference Guides
Detailed implementations in the references/ directory:
| Guide | Contents |
|---|---|
| The 5 Whys Technique | The 5 Whys Technique |
| Systematic RCA Process | Systematic RCA Process |
| RCA Report Template | RCA Report Template |
| Root Cause Analysis Techniques | Root Cause Analysis Techniques |
| Follow-Up & Prevention | 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
Follow-Up & Prevention
Follow-Up & Prevention
After RCA:
1. Track Action Items
- Assign owner
- Set deadline
- Follow up in retrospective
2. Prevent Recurrence
- Automated tests
- Monitoring/alerts
- Procedural changes
- Training
3. Monitor Metrics
- Track similar incidents
- Verify fix effectiveness
- Monitor preventive measures
- Catch early warnings
4. Share Learnings
- Document incident
- Share with team
- Industry sharing if relevant
- Update procedures
---
Checklist:
[ ] Incident details documented
[ ] Timeline established
[ ] Logs reviewed
[ ] Metrics analyzed
[ ] Root cause identified (via 5 Whys)
[ ] Contributing factors listed
[ ] Immediate actions completed
[ ] Short-term solutions planned
[ ] Long-term solutions identified
[ ] Solutions prioritized
[ ] RCA report written
[ ] Team debriefing scheduled
[ ] Action items assigned
[ ] Prevention measures planned
[ ] Follow-up scheduledRCA Report Template
RCA Report Template
RCA Report:
Incident: Database connection failure (2024-01-15, 14:30-15:15)
Impact:
- Duration: 45 minutes
- Users affected: 5,000 (10% of user base)
- Revenue lost: ~$2,000
- Severity: P1 (Critical)
Timeline:
14:30: Automated monitoring alert: High error rate (20%)
14:32: On-call engineer notified
14:35: Identified database connection error in logs
14:40: Restarted database connection pool
14:42: Service recovered, error rate returned to 0.1%
14:50: Incident declared resolved
15:15: Full recovery verified
Root Cause:
Poorly optimized query introduced in release 2.5.0 caused
queries to take 10x longer. Connection pool exhausted as
connections weren't released quickly.
Contributing Factors:
1. No query performance testing pre-deployment
2. Load testing environment doesn't match production volume
3. No alerting on query duration
4. Connection pool timeout set too high
Solutions:
Immediate (Done):
- Rolled back problematic query optimization
Short-term (1 week):
- Added query performance alerts (>1s)
- Added index for slow query
- Set query timeout to 5 seconds
Long-term (1 month):
- Updated load testing with production-like data
- Implement performance benchmarks in CI/CD
- Improve monitoring for connection pool health
- Training on query optimization
Prevention:
- Query performance regression tests
- Load testing with production data
- Connection pool metrics monitoring
- Code review of database changesRoot Cause Analysis Techniques
Root Cause Analysis Techniques
Fishbone Diagram:
Main problem: Slow API Response
Branches:
Code:
- Inefficient algorithm
- Missing cache
- Unnecessary queries
Data:
- Large dataset
- Missing index
- Slow database
Infrastructure:
- Low CPU capacity
- Slow network
- Disk I/O bottleneck
Process:
- No monitoring
- No load testing
- Manual deployments
People:
- Lack of knowledge
- Lack of tools
- No peer review
---
Systemic vs. Individual Causes:
Individual: "Developer used inefficient code"
Fix: Training
Risk: Happens again with different person
Systemic: "No code review process"
Fix: Implement mandatory code review
Risk: Prevents similar issues
Prefer systemic solutions for preventionSystematic RCA Process
Systematic RCA Process
Step 1: Gather Facts
- When did issue occur?
- Who detected it?
- How many users affected?
- What error messages?
- What system changes deployed?
- Check logs, metrics, alerts
- Determine impact scope
Step 2: Reproduce
- Can we reproduce consistently?
- What are the exact steps?
- What environment (prod, staging)?
- Can we isolate to component?
- Set up test case
Step 3: Identify Contributing Factors
- Direct cause
- Indirect/enabling factors
- System vulnerabilities
- Procedural gaps
- Knowledge gaps
Step 4: Determine Root Cause
- Use 5 Whys technique
- Ask "why did this control fail?"
- Look for systemic issues
- Separate root cause from symptoms
Step 5: Develop Solutions
- Immediate: Fix the symptom
- Short-term: Prevent recurrence
- Long-term: Systemic fix
- Prioritize by impact/effort
Step 6: Implement & Verify
- Implement solutions
- Test in staging
- Deploy carefully
- Verify improvement
- Monitor metrics
Step 7: Document & Share
- Write RCA report
- Document lesson learned
- Share with team
- Update procedures
- Training if neededThe 5 Whys Technique
The 5 Whys Technique
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#!/bin/bash
# validate-schema.sh - Validate database schema
# Usage: ./validate-schema.sh <schema_file>
set -euo pipefail
SCHEMA_FILE="${{1:?Usage: $0 <schema_file>}}"
echo "Validating schema: $SCHEMA_FILE"
# TODO: Add schema validation
# - Check SQL syntax
# - Verify foreign key references
# - Check index definitions
# - Validate naming conventions
# - Check for missing constraints
echo "Schema validation complete."
-- Migration: [description]
-- Created: [date]
-- TODO: Customize for your migration framework
BEGIN;
-- Up migration
-- TODO: Add schema changes
-- CREATE TABLE IF NOT EXISTS ...
-- ALTER TABLE ...
-- Down migration (rollback)
-- TODO: Add rollback statements
-- DROP TABLE IF EXISTS ...
COMMIT;
Related skills
Azure DiagnosticsSystematically diagnose and resolve production issues on Microsoft Azure using official Microsoft guidance.495k1.3kAzure MessagingQuickly diagnose and fix connection, authentication, and message-processing failures when using Azure Event Hubs or Service Bus SDKs.483k1.3k
Diagnosing BugsGet a systematic, step-by-step process that surfaces the real root cause instead of guessing at bugs.291k200k
Use My BrowserWhen their agent task requires access to the live browser session, rendered DOM state, authenticated dashboards, localhost apps, or DevTools-selected elements instea269k71
Systematic DebuggingFollow a repeatable four-phase process that forces root-cause discovery before any code changes.210k265k
Safe DebugGet conservative, non-destructive diagnosis of deep learning and agent errors before any code changes are made.185k512How it compares
Pick root-cause-analysis over generic debugging skills when the deliverable is a team-facing incident report, not code-level bug isolation.
FAQ
What does root-cause-analysis produce?
root-cause-analysis produces a structured incident RCA: timeline, log and metrics review, 5 Whys root cause, contributing factors, prioritized fixes with owners, and a prevention checklist covering tests, monitoring, and procedural changes.
When should teams use root-cause-analysis?
Teams should use root-cause-analysis after production incidents when they need documented postmortems with follow-up prevention—not for quick hotfix notes or trivial local bugs without operational impact.
Is Root Cause Analysis safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.