rca

name

rca

description

Root-cause analysis for code. Use when a defect shipped and was caught after the fact, a run came back BLOCKED or a deliverable failed validation, a bug recurs after a prior fix, or the user says 'rca this', 'root cause this', 'postmortem this', or 'why did this break'. Produces a structured RCA that separates surface from structural cause, demands evidence-backed verification, and tracks action items. Also covers prospective premortems.

RCA Skill

The diagnostic counterpart to forward planning. When a failure gets past a test, a gate, or review, write a root-cause analysis to the canonical template. The goal is never who, it is: what guardrail was missing and why the mistake was easy to make.

Before writing

Read references/rca-template.md. It is the canonical structure and the exact contract the lint enforces. Do not improvise a different shape.

When to write an RCA

• A defect shipped and a human or a gate caught it after the fact.
• A run came back BLOCKED, or a deliverable failed validation.
• A bug recurs after a prior fix (the prior fix treated a symptom).
• The user says "rca this", "root cause this", "postmortem this", "why did this break".

A trivial bug you fix in the same breath, that never escaped a gate, does not need an RCA. A failure that got past a test, a gate, or review does.

Where RCAs land

q-system/output/rca/rca-<slug>-<YYYY-MM-DD>.md inside a kipi instance, or rca/rca-<slug>-<YYYY-MM-DD>.md in a plain repo. The lint fires on any file named rca-*.md / premortem-*.md or any doc whose H1 starts with # RCA: or # Premortem.

The rules the lint enforces

1. Surface vs structural root cause. Surface is the trigger (what fired). Structural is the latent systemic cause (why it was allowed and went uncaught).
2. Multi-factor. Use ### Root cause #1, ### Root cause #2 when more than one structural cause contributed. Resist a single tidy cause.
3. Cause-type tags. Each structural cause carries a type: line, one of: code-defect, config, environmental-trigger, missing-test, implicit-contract, process, capacity.
4. Verification is evidence. Show the command and result ("ran X, got Y") or the passing test. An assertion with no observed output is not verification.
5. Action items are checkboxes with owners. Not prose. An RCA is not finished until its actions are owned and trackable.
6. Blameless. Describe system, contract, gate, and test failures. Never name a person as the cause.

The deterministic notify

The rca-notify hook watches command results. When a test or run fails (non-zero exit, or FAIL / BLOCKED / Traceback in the output), it injects a nudge to open an RCA. That is the shoulder-tap. The skill is how you answer it.

Premortem variant

Before shipping a high-trust deliverable, run a premortem instead: assume it already failed in front of the customer and enumerate how. Structure is in the template under "Premortem variant".

Enforcement

scripts/rca-lint.py validates every RCA/premortem doc on write. Bypass a single file with <!-- rca-lint-skip --> (intentional exceptions only).