/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).