Root Cause Analysis

Use this skill when the user wants なぜなぜ分析, root cause analysis, RCA, postmortem analysis, incident analysis, accident-style investigation, or an explanation of why a previous diagnosis failed. The output must identify what must be changed to prevent recurrence. A chain of five guesses is not enough.

Core Standard

RCA is complete only when these claims are evidence-backed:

• what happened;
• where the analysis boundary is;
• which causal factors are proven, suspected, contradicted, or unknown;
• which factors are proximate triggers, contributing conditions, detection failures, organizational/process failures, or lesson-retention failures;
• which concrete surfaces must change;
• how those changes will be verified and how similar failures will be searched for.

Never claim a root cause just because it is plausible. Treat uncertain evidence as incomplete.

Start Here

1. State the incident in one falsifiable sentence: observed bad outcome, affected artifact/system/user, exact time or version when known, and why the outcome mattered.
2. Gather evidence before asking why. Inspect current files, logs, rollouts, commits, configs, tests, reports, tickets, screenshots, traces, and prior session records that can prove or contradict each causal step.
3. Build a timeline from evidence. Separate "what happened" from "why it happened".
4. List at least two causal branches unless the incident is demonstrably trivial. Include direct trigger, missed detection, missing gate, process/skill/runbook/memory gap, and environment/tooling conditions when relevant.
5. Ask why down each branch. Stop neither at five whys nor at the first plausible human explanation. Continue until the next cause is outside the task authority, is not actionable, or is already covered by a concrete countermeasure.
6. For each candidate root/contributing cause, run a counterfactual test: if this condition had been removed or changed, would the original bad outcome or class of outcome have been prevented or detected in time?
7. Convert accepted causes into fix surfaces: exact file, script, skill, runbook, test, gate, config, process owner, or command that must change.
8. Define verification gates before completion: deterministic tests, scanners, negative fixtures, replay/smoke evidence, review criteria, or live-system checks that prove the recurrence class is blocked.

Evidence Discipline

Create an evidence ledger with one row per important claim:

• claim_id
• claim
• evidence
• status: proven, contradicted, unknown, or needs_more_evidence
• source: path, command, URL, rollout line, commit, log, or observation

Use exact paths and line numbers for local evidence. When the user explicitly asks for web research or when facts may have changed, browse and cite sources. For current OpenAI/Codex behavior, prefer official OpenAI docs and local source over memory.

Do not rely on recollection, a previous final answer, or a green command unless the command covers the actual requirement.

Causal Model

Use more than one model when the system is complex:

• 5 Whys for local causal chains.
• Fishbone or branch list for multiple causes.
• Barrier analysis for "what should have stopped this and why did each barrier fail?"
• AcciMap-style levels for sociotechnical incidents: operator/session, tooling, repo/process, organization/lesson retention, external constraints.
• Timeline plus change history for software regressions.
• Postmortem action mapping for incident recurrence prevention.

Avoid these failure modes:

• a single linear chain for a multi-factor incident;
• "human error", "forgot", "careless", "insufficient attention", "education", "be careful", or "double-check" as the terminal root cause;
• stopping at direct cause when the missing prevention/detection mechanism is the real fix surface;
• treating "known in the past" as "operationalized now";
• reporting that a cause is known without proving the future task would encounter it through a skill, runbook, scanner, test, memory, or gate;
• proposing actions without owners, changed artifacts, and verification.

Output Shape

For serious RCA, produce these sections:

• Incident Statement: one falsifiable sentence.
• Scope And Impact: what is included, excluded, and why the analysis depth is appropriate.
• Evidence Ledger: compact table or bullets with statuses.
• Timeline: ordered events with sources.
• Causal Map: branch list, barrier analysis, or AcciMap-style levels.
• Why Analysis: why chains per branch, with evidence status on each step.
• Counterfactual Tests: what would have prevented, detected, or limited the incident.
• Root And Contributing Causes: distinguish terminal actionable root causes from triggers and contributors.
• Required Fix Surfaces: exact files, skills, scripts, tests, commands, process gates, or owners.
• Verification Plan: deterministic checks, negative fixtures, replay, smoke tests, and acceptance gates.
• Residual Risk And Unknowns: what remains unproven and what evidence would close it.

For small incidents, you may compress the sections, but do not omit evidence, fix surfaces, or verification.

Completion Gate

Do not mark the analysis complete until:

• every explicit user concern has a row in the evidence ledger;
• every accepted cause has a counterfactual test;
• every root cause maps to at least one concrete fix surface;
• every fix surface has a verification gate;
• known previous incidents and lessons were searched when the user references past sessions, known history, or recurrence;
• the final recommendation states exactly what should be changed next.

If the task asks you to create or update a skill/runbook/test so future Codex sessions catch the issue, completion requires editing that durable surface and verifying that the updated surface is discoverable or executable.

Local Evaluation Helper

Use the audit helper to check whether an RCA report has the minimum structure expected by this skill:

python3 /path/to/root-cause-analysis/scripts/root_cause_analysis_audit.py \
  --report /absolute/path/to/root-cause-report.md

Run the self-test after edits:

python3 /path/to/root-cause-analysis/scripts/root_cause_analysis_audit.py --self-test

The helper is not proof of correctness. It catches shallow reports that lack evidence, branches, counterfactuals, fix surfaces, or verification gates.

Research Basis

See references/root-cause-analysis-research-ledger.md for the sources used to design this workflow, including OpenAI skill/eval guidance, NTSB accident investigation practice, NASA/JAXA/IPA incident-learning material, Google SRE postmortem guidance, ASQ 5 Whys guidance, and critiques of 5 Whys as a standalone RCA tool.