Application incident root cause analyzer · free AI skill

Produces a structured post-incident root cause analysis using 5 Whys and fishbone methodology, categorizing contributing factors across code, config, infrastructure, and process, with a ranked corrective action plan and…

Purpose

Transform raw incident data — timeline, symptoms, topology, and change log — into a rigorous, blameless root cause analysis that separates the triggering cause from contributing factors and outputs prioritized corrective actions. Eliminates shallow "human error" conclusions and produces a postmortem an engineering organization can act on.

When to Use

Invoke this skill when the user asks to:

Conduct a post-incident review or write a postmortem
Determine why a production outage or degradation occurred
Analyze an incident using 5 Whys or fishbone methodology
Identify contributing factors and corrective actions after an incident
Reconstruct an incident timeline and pinpoint the root cause
Prepare a blameless RCA document for stakeholders or leadership

Inputs Required

Before starting, collect:

Incident summary: What broke, user-facing impact, severity/priority level
Incident timeline: Timestamped sequence — detection, escalation, mitigation, resolution (include time-to-detect and time-to-resolve if available)
Symptoms observed: Error messages, alerts, metrics/graphs, log excerpts, affected endpoints or services
System topology: Affected services and their dependencies (databases, queues, upstream/downstream services, third parties)
Change log: Deploys, config changes, infra changes, feature flags, or schedule changes in the window before the incident
Detection method: How the incident was noticed (alert, customer report, monitoring, manual)
Mitigation taken: What action stopped the impact (rollback, restart, scale, failover, config revert)

If the change log is missing, treat "no recorded change" as a finding and flag change-tracking as a process gap. Default severity to Sev-2 if unstated.

Instructions

Step 1: Reconstruct the Blameless Timeline

Build a clean, factual sequence of events. For each entry: timestamp, event, actor (system or role — never named individuals), and evidence source.

Distinguish impact start (when users were affected) from detection (when the team knew) from resolution (when impact ended)
Calculate and surface: time-to-detect (TTD) and time-to-resolve (TTR)
Flag detection gaps: if TTD is large relative to impact, note it as a monitoring finding for later
Keep language neutral — "the deploy at 14:02 introduced the regression," not "the engineer broke it"

Step 2: Establish the Triggering Event

Identify the single change or condition that immediately preceded the failure. Cross-reference the change log against impact start.

If a change correlates tightly in time, name it as the probable trigger and state the confidence level (High / Medium / Low)
If no change correlates, investigate load-based, data-based, or dependency-based triggers (traffic spike, poison message, expired cert, upstream degradation)
State the trigger as a factual claim tied to evidence, not a guess

Step 3: Run the 5 Whys

Starting from the user-facing symptom, ask "why" iteratively until reaching a systemic cause — not a person.

Why 1: Why did users experience the impact?
Why 2: Why did that condition occur?
Why 3: Why was that condition possible?
Why 4: Why did the system/process allow it?
Why 5: Why did no control catch it earlier?
Stop when the answer points to a systemic gap (missing test, absent guardrail, gap in review process). If "human error" appears, keep asking — the real root cause is the missing safeguard that let the error reach production.
Branch when there are two independent causal chains; run 5 Whys on each.

Step 4: Build the Fishbone (Ishikawa) Analysis

Organize all contributing factors into four categories. A contributing factor made the incident more likely, larger, or longer — but was not necessarily the trigger.

Code — logic defects, unhandled edge cases, missing error handling, race conditions, insufficient test coverage, dependency version issues

Config — misconfigured limits/timeouts/retries, wrong feature flag state, secrets/cert expiry, environment drift, incorrect scaling thresholds

Infrastructure — resource exhaustion (CPU/memory/disk/connections), network/DNS issues, single points of failure, capacity limits, third-party/cloud provider faults

Process — inadequate testing/staging, gaps in deploy or rollback procedure, missing monitoring/alerting, insufficient on-call runbook, change management gaps, communication/escalation delays

For each category, list only factors supported by the evidence. Mark each factor as Root Cause, Contributing Factor, or Amplifier (worsened impact/duration without causing it).

Step 5: State the Root Cause and Contributing Factors

Write a clear root cause statement (2–3 sentences) that a reader unfamiliar with the incident can understand. Then list the ranked contributing factors and amplifiers, each tagged with its fishbone category.

Step 6: Generate Corrective Actions

Produce corrective actions in three horizons, each mapped to the factor it addresses:

Immediate (0–7 days): Restore safety — add the missing alert, patch the defect, revert the risky config, add the rollback safeguard
Short-term (1–4 weeks): Close the systemic gap — add the missing test, fix the deploy pipeline, tune the scaling threshold
Long-term (1–3 months): Prevent the class of failure — architectural change, remove SPOF, improve change management or observability strategy

For each action include: owner role (not a name), priority (P0/P1/P2), the factor it addresses, and a detection/prevention improvement (would this action have caught or prevented this incident?).

Step 7: Assess Detection and Response

Summarize how well the incident was detected and handled, with specific improvements:

Was detection automated or reactive? Target: alert before customer report.
Did the runbook cover this scenario? If not, note the runbook gap.
Were escalation and communication timely? Flag delays with timestamps.

Output Format

Structure: Structured postmortem document with clear section headers; timeline as a table; fishbone as four labeled categories; corrective actions as a ranked table
Length: 1,000–1,500 words
Format: Structured document — mix of tables (timeline, corrective actions) and labeled lists (5 Whys, fishbone)
Sections: Incident Summary → Blameless Timeline (table) → Triggering Event → 5 Whys Analysis → Fishbone Contributing Factors (Code/Config/Infra/Process) → Root Cause Statement → Corrective Actions (Immediate/Short-term/Long-term table) → Detection & Response Assessment
Tone: Blameless, analytical, precise — an SRE writing for engineers and leadership. No naming of individuals; systemic focus throughout.

Quality Checklist

Before delivering output, verify:

[ ] Timeline separates impact start, detection, and resolution — with TTD and TTR surfaced
[ ] The 5 Whys terminates at a systemic cause, not "human error" or a named person
[ ] Every fishbone category (Code, Config, Infrastructure, Process) is addressed — even if only to note "no factors identified"
[ ] Each contributing factor is tagged Root Cause / Contributing Factor / Amplifier
[ ] Every corrective action maps to a specific factor and includes owner role, priority, and horizon
[ ] At least one corrective action improves detection or prevention of this incident class
[ ] The document contains no individual names — language is blameless throughout

Notes

The most common shallow conclusion is stopping the 5 Whys at "someone made a mistake" — the real root cause is always the absent control that let the mistake reach production.
If two independent causal chains exist (e.g., a code defect AND a missing alert that delayed detection), document both — most serious incidents are multi-causal.
When the change log shows no changes but impact began suddenly, prioritize data-driven and dependency triggers: poison messages, cert/token expiry, quota exhaustion, and upstream degradation.
Corrective actions with an owner role and priority but no due horizon tend not to get done — always place each action in a time horizon.

How to use this skill

This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.

Installing in Claude Code:

~/.claude/skills/<folder-name>/SKILL.md — auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)
<your-project>/.claude/skills/<folder-name>/SKILL.md — auto-loads only when working in that project (recommended for project-specific skills)

Restart Claude Code or open a new session to register.

Using in Claude.ai, ChatGPT, Gemini, or other AI tools:

Drag this file into a new chat, or copy and paste its contents
Send your task or request as your next message — the AI will apply the skill where it fits

For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills