rca

name

rca

description

Root Cause Analysis thinking tool for technical problem-solving. Use this skill immediately and without hesitation whenever the user mentions "RCA", "root cause", "incident analysis", "post-mortem", or asks why something broke, failed, or is behaving unexpectedly in a system, codebase, or infrastructure context. Also trigger when a developer or admin describes a fault and appears to want structured diagnosis rather than a quick fix. This skill drives a Socratic dialogue that walks the user through the analysis, then produces a structured incident document.

Root Cause Analysis (RCA) Skill

A structured thinking tool for technical fault diagnosis. Drives a Socratic dialogue grounded in two core axioms, then produces a formal incident document.

---

Core Axioms

These two questions constrain the hypothesis space. Return to them whenever the analysis stalls or hypothesis count grows unwieldy.

Axiom 1 — Comparative isolation

"This but not that — why?" What exhibits the symptom? What doesn't? The difference between them is where the cause lives. Force specificity: same network but different host? Same host but different service? Same service but different input?

Axiom 2 — Negative space

"What could have failed, but hasn't — and why?" What is conspicuously still working? Its continued operation is evidence. Use it to rule out whole classes of hypothesis.

---

Epistemological Frame

Every claim in an RCA is one of two things:

Type	Definition	Obligation
Hypothesis	A candidate explanation	Must be falsifiable. Name the evidence that would disprove it.
Assumption	A premise taken as true without direct evidence	Must be surfaced, stated explicitly, and tested where possible

An assumption presented as a fact is a diagnosis error waiting to happen. Surface assumptions early; convert them to evidence or discard them.

---

Dialogue Flow

Work through these phases in sequence. Revisit earlier phases if new evidence contradicts established framing.

Phase 1 — Problem Statement

Ask the user to describe:

1. What is the observed symptom? (exact behaviour, error message, metric deviation)
2. When was it first observed? Is it continuous or intermittent?
3. What is the impact? (scope: users, services, data; severity: degraded vs total loss)

After the user responds, restate the problem statement in your own words and ask them to confirm or correct it before proceeding. A wrong problem statement produces a correct answer to the wrong question.

Phase 2 — Comparative Isolation (Axiom 1)

Ask targeted comparative questions to isolate the fault domain:

• Does the symptom appear on all instances / environments / inputs, or only some?
• What changed recently? (deployments, config, infrastructure, load patterns)
• Has this symptom appeared before? Under what conditions?

As answers arrive, explicitly name what is ruled in and what is ruled out.

Phase 3 — Hypothesis Formation

Generate 2–4 candidate hypotheses. For each:

• State it as a falsifiable claim
• Identify the assumptions it rests on
• Name the evidence that would confirm it
• Name the evidence that would eliminate it

Apply Axiom 2: for each hypothesis, ask whether there is something that should also be broken if this hypothesis were true — and isn't. If the negative space contradicts the hypothesis, say so.

Phase 4 — Evidence Gathering

For each hypothesis, identify what evidence exists and what gaps remain:

• Available: logs, metrics, traces, stack traces, config diffs, test results
• Needed: what to query, instrument, or reproduce

Ask the user to provide evidence. On receipt, update each hypothesis: confirmed / eliminated / still possible / revised.

Repeat Phase 3–4 as needed until one hypothesis survives or a clear root cause is established.

Phase 5 — Root Cause Statement

State the root cause as a single, precise sentence. It should:

• Identify the specific component or condition that failed
• Explain the causal chain to the observed symptom
• Be grounded in evidence, not assumption

If certainty is incomplete, say so. A qualified root cause is more honest and more useful than a confident guess.

Phase 6 — Incident Document

Generate the structured output (see template below). Ask the user if they want to add anything before finalising.

---

Incident Document Template

# Incident Report

**Date:** [YYYY-MM-DD]
**Status:** [Open / Resolved / Monitoring]
**Severity:** [Critical / High / Medium / Low]
**Reporter:** [name or role]

---

## Problem Statement
[One or two sentences. What broke, when, and what was the impact.]

## Timeline
| Time | Event |
|------|-------|
| HH:MM | [observed symptom / action taken] |

## Comparative Analysis
**Affected:** [what exhibited the symptom]
**Unaffected:** [what did not — and what that rules out]

## Hypotheses Considered
| # | Hypothesis | Status | Basis for elimination or confirmation |
|---|-----------|--------|---------------------------------------|
| 1 | ... | Eliminated / Confirmed | ... |

## Assumptions Surfaced
- [Assumption and whether it was validated]

## Root Cause
[Single precise statement of root cause, with evidence cited]

## Causal Chain
[Step-by-step: from root cause to observed symptom]

## Contributing Factors
[Conditions that made the fault possible or worsened impact]

## Corrective Actions
| Action | Owner | Priority | Status |
|--------|-------|----------|--------|
| ... | ... | ... | ... |

## Preventive Measures
[Systemic changes to prevent recurrence]

## Lessons Learned
[What the analysis revealed beyond the immediate fix]

---

Behavioural Notes

• Never jump to root cause before Phase 3. The symptom is not the cause.
• Surface assumptions explicitly. When the user states something as fact, ask what the evidence is. Do this gently but consistently.
• Name what is ruled out. Stating eliminations is as important as stating hypotheses — it shows the reasoning isn't circular.
• Keep hypotheses falsifiable. "Something is wrong with the network" is not a hypothesis. "Packet loss between service A and the DB on subnet X" is.
• Don't pad the incident document. Leave sections blank rather than fill them with speculation. Mark unknowns explicitly as [unknown — requires further investigation].