root-cause-frameworks

root-cause-frameworks

Structured root-cause analysis for resolved incidents and recurring bugs. Sibling of systematic-debugging (live reproduction loop) and bug-analyzer (static call-site analysis) — this skill takes the post-resolution "why did this happen and how do we stop it recurring?" view.

When to use

• A resolved incident needs a structured cause investigation before writing the post-mortem.
• A bug recurs and the team needs to understand the underlying system condition, not just the symptom.
• Invoked directly or by blameless-post-mortem to populate the cause section.

Do NOT use when:

• Actively debugging a failing test or unresolved crash — use systematic-debugging instead.
• The goal is to enumerate call-site impact of a change — use blast-radius-analyzer instead.

Procedure

Work through the three methods in order; return the best-supported result.

1. 5-Whys chain

Ask "Why did X happen?" iteratively, attaching evidence to each link. Continue until the link is unfalsifiable, evidence runs out, or you reach a systemic condition outside the team's control.

Rules:

• Each link must cite at least one piece of evidence (log line, metric, test failure, code path, human observation). Label unverified links explicitly as [speculative].
• If a link branches into two independent causes, follow both — a branching chain is common and valid.
• Stop a branch when: (a) the next Why has no available evidence, or (b) the answer is outside the system boundary (e.g. "the cloud provider had an outage").

2. Fishbone / Ishikawa (if chain stalls or branches widely)

When the 5-whys chain stalls before reaching a systemic cause, or branches into more than three independent paths, map contributing factors across six categories:

List each identified factor as a bullet under its category. A factor may appear in more than one category — that is evidence of a systemic coupling worth naming.

3. Contributing-factors split

Classify every cause surfaced in steps 1–2 into exactly one bucket:

A well-formed analysis typically has one root cause and two to four contributing causes. Multiple root entries indicate the chain has not been traced far enough, or that the incident was a genuine compound failure — label it explicitly.

Output

The output has three ordered sections:

1. Why-chain — numbered chain, each link with evidence (or [speculative] flag) and any branch markers.
2. Cause taxonomy — each identified cause labelled root / contributing / amplifying / coincidence, with a one-sentence justification.
3. Evidence gaps — explicit list of claims that could not be verified and what evidence would resolve them. An empty list is fine; omitting the section is not.

May invoke systematic-debugging or bug-analyzer mid-procedure to gather evidence for a specific hypothesis, then continue the analysis.

Do NOT

• Do NOT present a [speculative] link as confirmed cause.
• Do NOT collapse multiple contributing factors into a single root cause to produce a cleaner narrative.
• Do NOT invent evidence — if a log line is needed but unavailable, name the gap.
• Do NOT reproduce the systematic-debugging reproduce → isolate → fix loop; this skill assumes the bug is already understood or resolved.

Gotchas

• Single "root cause" is often an oversimplification — a compound failure with one root and several contributing causes is the norm, not an edge case.
• An unfalsifiable why-link (e.g. "we don't know") is a stop signal for that branch; do not guess past it.
• Correlation ≠ causation — require a causal mechanism for every link, not just temporal proximity.

See also

• blameless-post-mortem — invokes this skill for the cause section.
• systematic-debugging — live reproduction and fix loop.
• bug-analyzer — static call-site analysis.
• risk-officer — mitigation framing for corrective actions after the cause is established.