| name | Five Whys Root Cause Analysis |
| description | Evidence-based root cause diagnosis using a branching five-whys investigation. Produces a likelihood-ranked list of candidate root causes — diagnosis only, never a fix. Use ONLY when the user explicitly asks to diagnose a problem or find a root cause, with phrases like "find the root cause", "diagnose this", "do a five whys check", "root cause analysis", "why is this happening", or "run a five whys". Do NOT trigger on generic mentions of errors, bugs, or fix requests. |
| version | 0.2.0 |
Five Whys Root Cause Analysis
Purpose
Identify the root cause(s) of a reported problem through systematic, evidence-based
investigation — and stop there. This skill diagnoses; it does not fix. Diagnosis is
deliberately decoupled from solution so the user can review the findings and decide what
to do next.
The deliverable is a likelihood-ranked list of candidate root causes, each backed by
concrete evidence and a stated confidence level.
When this skill applies
Trigger only on an explicit diagnostic request — e.g. "find the root cause of X",
"diagnose this", "do a five whys check", "run a root cause analysis", "why is this
happening". Do not trigger on a bare bug report or a "fix this" request. If the user
just wants something fixed, this skill is not in scope.
Core problem this prevents
The default failure mode when facing a problem:
- Observe symptom
- Speculate about cause
- Implement a speculative fix
- Fix doesn't work or creates new problems
- Repeat indefinitely
This skill breaks that loop by forcing evidence before conclusions and by separating
the act of diagnosis from the act of fixing.
How to investigate
Conducting the investigation
Read whatever you need, reason about the evidence, and assemble the ranked list. You may
read any and all files you judge relevant to finding the root cause — error sites, call
sites, dependencies, configs, tests, logs. Follow the evidence wherever it leads; do not
artificially limit which files you open.
Use subagents freely. When the investigation is large or naturally parallel — e.g. each
hypothesis from Phase 1 can be branch-tested independently, or a wide codebase needs
sweeping — dispatch subagents (the Explore agent for read-only searches, or general
agents) to investigate branches concurrently and report evidence back. Have each subagent
return its findings (causal chain, evidence, refute/support verdict); you synthesize the
results into the ranked list. This keeps the main context focused and speeds up
breadth-first investigation.
Phase 0 — Define the problem
Before asking a single "why", pin down what you're actually diagnosing. A vague symptom
guarantees a low-confidence result.
- Review current context first. Re-read what the user already said, the error/output
in the transcript, and the relevant code. Most of what you need to frame the problem is
usually already in front of you — extract it before asking anything.
- State the problem precisely: what is the observed behavior, what is the expected
behavior, and how do you know they differ. If you can't articulate "expected vs.
actual", you don't yet have a problem definition.
- Ask clarifying questions only if something genuinely blocking is missing — and only
after step 1 confirms it isn't already available. Don't interrogate. Batch questions
into one short round, ask only what changes the investigation, and prefer concrete asks
("can you paste the error log / the failing command output?") over open-ended ones. If
the context is sufficient, skip this and proceed.
Phase 1 — Enumerate hypotheses, then branch-test
Do not commit to the first causal chain that comes to mind — that tunnel vision is a
top cause of low-confidence output. Instead:
- Brainstorm the candidate causes up front. List every plausible cause of the symptom
you can think of, given the evidence so far. Breadth here is cheap and prevents missing
the real one.
- Then branch-test each. Treat the list as the top level of a causal tree and
investigate each candidate with the branching five-whys below. Discard branches the
evidence refutes; deepen the ones it supports.
Phase 2 — The branching five-whys
For each surviving hypothesis, start from the symptom and iteratively ask "why?", grounding
every answer in evidence you actually checked. "Five" is just a name — continue until you
reach an actionable root cause, however many levels that takes.
Causal chains branch. Real problems often have more than one contributing cause at a
given level. When a "why" has multiple plausible answers supported by evidence, split
into branches and pursue each. Track the result as a small causal tree, not a single
rope. Different branches may terminate in different root causes — that's expected, and all
surviving candidates belong in the final ranked list.
Symptom
├── Hypothesis A ──→ Why? → Cause ──→ Why? → Root cause A1
│ └→ Why? → Root cause A2
├── Hypothesis B ──→ Why? → Root cause B1
└── Hypothesis C ──→ [refuted by evidence — discarded]
Evidence-based answers
For each "why", gather concrete evidence before answering:
- Read the code that actually runs — files in error messages, call stacks, related
modules and dependencies.
- Examine outputs — error messages, stack traces, logs, console output, test results.
- Check configuration — environment variables, config files, build settings,
dependency versions.
- Verify assumptions — don't assume; check actual behavior and actual values present.
Base each answer on evidence, not speculation. If a branch rests on an unverified
assumption, either verify it or mark that candidate's confidence down accordingly.
What counts as a root cause
A candidate qualifies as a root cause when:
- Actionable — could be addressed with a code, config, or data change within our
control. (We are not fixing it here — only confirming a fix is conceivable.)
- Directly explanatory — fully accounts for the symptom along its branch, with no
gaps in the causal chain. Removing this cause would eliminate the symptom.
- Terminal — the next "why" would go outside our control (external system,
architectural decision, business requirement) or would not lead anywhere more
actionable.
Root cause vs. symptom restatement
Symptom: "Tests are failing"
- ❌ Not a root cause: "The test expectations are wrong" (what made them wrong?)
- ❌ Not a root cause: "The code doesn't match tests" (why doesn't it match?)
- ✅ Root cause: "Function returns null when
user.profile is undefined, but tests expect an empty object"
Symptom: "API returns 404"
- ❌ Not a root cause: "Route doesn't exist" (why doesn't it exist?)
- ✅ Root cause: "Route path is
/api/v1/users but code defines /api/users — missing /v1 prefix"
Don't stop at: symptom restatements, vague causes ("there's a config issue"), or the first
plausible explanation without verification.
Confidence gate
After assembling candidates, state your confidence in the top-ranked candidate —
high, medium, or low — and say what drove that rating. The skill terminates cleanly
only at high confidence. Anything less means there is more investigation to do, so loop
back rather than presenting prematurely.
If confidence is below high — diagnose why, then act
Low or medium confidence is itself a symptom. Identify which of these is the cause and
apply the remedy before re-ranking:
| Reason for low confidence | Remedy |
|---|
| Incomplete hypothesis set — committed to one chain without enumerating alternatives | Return to Phase 1; brainstorm the full candidate list, then branch-test each |
| Missing critical information — no logs, stack trace, runtime values, version info | Name the specific missing artifact; ask the user for it (or where to find it), or obtain it yourself |
| Unverified assumption in the chain — a "why" was a guess, never checked | Go verify it against actual code/values; if unverifiable, mark that candidate down |
| Non-discriminating evidence — two+ candidates fit equally well | Find a disambiguating observation that only one candidate predicts |
| Correlation, not causation — suspicious code but no proven link to the symptom | Trace the actual execution path from symptom back to the suspected cause |
| Ill-defined symptom — expected vs. actual still unclear | Return to Phase 0; resolve what "correct" looks like |
| Stale / conflicting evidence — code doesn't match what's running, or sources disagree | Reconcile which source is authoritative before trusting it |
| Intermittent / non-deterministic — race, flake, load-dependent (a confidence ceiling) | Note the timing/concurrency factor; declare the ceiling rather than spinning |
| Inaccessible / opaque component — external service or code you can't inspect (a ceiling) | Mark the branch as a boundary; the candidate stays explicitly hypothetical |
Re-investigate and re-rank. Loop until confidence reaches high — or a full pass turns
up no new evidence and the only remaining limiters are genuine ceilings (intermittent,
opaque). In that terminal-but-uncertain case, present the best-effort ranked list and state
plainly that confidence is capped, which reason caps it, and what would lift it.
If confidence is high — pressure-test, then present
Before presenting, pressure-test the diagnosis by invoking the phone-a-friend skill
(via the Skill tool). Frame it as adversarial review of the top candidate: hand the friend
the symptom, the causal chain, and the evidence you relied on, and ask it to refute the
diagnosis or surface a more likely cause. Fold the outcome — confirmation, a downgrade, or
a new candidate — into the ranked list before showing it to the user. Rationale: a
confident-but-wrong diagnosis is the most dangerous output, and high confidence is the
skill's clean exit, so it earns one adversarial check before it ships.
Output format
Present findings as a ranked list. Do not propose or implement a fix.
## Root Cause Analysis: [symptom]
**Symptom observed:** [what was reported / observed]
**Files & evidence examined:** [key files, logs, outputs you inspected]
### Candidate root causes (most → least likely)
#### 1. [Candidate] — Likelihood: High · Confidence: [high/medium/low]
- **Causal chain:** Symptom → why → why → … → this cause
- **Evidence:** [concrete evidence: file:line, log excerpt, observed value]
- **Why it's a root cause:** [actionable · explanatory · terminal]
- **What would raise/lower confidence:** [if not high]
#### 2. [Candidate] — Likelihood: Medium · Confidence: [...]
- ...
#### 3. [Candidate] — Likelihood: Low · Confidence: [...]
- ...
### Confidence statement
Top candidate confidence: **[high/medium/low]** — [reasoning].
[If high: "Pressure-tested via phone-a-friend; outcome: …"]
Boundaries
- Diagnose, don't fix. Never edit code or propose an implementation as part of this
skill. If the user wants a fix, that's a separate, explicit request after they've
reviewed the diagnosis.
- Present multiple candidates ranked by likelihood — not a single answer — unless the
evidence genuinely supports exactly one.
- Ground everything in evidence. A candidate with no supporting evidence does not
belong on the list.
Success criteria
- ✅ Problem defined (expected vs. actual) before investigating; context reviewed before any clarifying question
- ✅ Hypotheses enumerated up front, then branch-tested — not a single committed chain
- ✅ Likelihood-ranked list of candidate root causes produced
- ✅ Each candidate backed by concrete evidence and a complete causal chain
- ✅ Confidence loop run: below-high confidence diagnosed via the taxonomy and re-investigated; clean exit only at high confidence or a declared ceiling
- ✅ phone-a-friend pressure-test run when confidence is high
- ✅ No fix proposed or applied
