Root Cause

---
name: root-cause
description: Finds the demonstrated cause of a defect, using deeper analysis for recurring or unclear failures. Use when a repair needs causal evidence.
---
<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

# Root Cause

Find the demonstrated cause of the observed failure. Stop when the cause and the approved repair are clear.

## Rules

- **A reproducible first defect is enough to act.** Fix its cause and add a focused regression.
- **Every link cites an observation.** A link that you reasoned to is where the chain becomes a story.
- **Stop at a cause you control.** A vendor decision or "the model was wrong" gives you nothing to build a control against.
- **Never stop on a person.** "Someone forgot" means the chain stopped early. Ask what let the mistake reach a commit.
- **Record competing causes when they change the repair.** Use an observation that distinguishes them.
- **Keep the repair within the approved outcome.** Record adjacent improvements separately; implement them when necessary for that outcome or separately authorized.

## 1. Reproduce the defect

Record the input, observed failure and expected behavior. A first reproducible defect can proceed directly to a focused fix and regression test. For a recurring or unclear failure, inspect relevant prior evidence and continue with the deeper analysis below.

## 2. Ask why

Ask why until the answer stops changing. Each link cites a `file:line`, a command and its output, a ledger row or a recorded verdict. When the next why leaves this repository, go back one link and build the control there.

At each link where a second answer was available, name it and say why you took the other one.

## 3. Test the chain

- **Per cause: would the removal of this cause block this path?** If the failure still reaches the same end, the cause is a condition you noticed. Continue the chain.
- **For the set: would the removal of all retained causes block the observed failure?** If a route stays open, a link is missing. That link is the one that needs the control.

A second person can run these two tests against your chain without a new derivation.

## 4. Output

| Field | Content |
| --- | --- |
| Control | A check, a gate, a schema field or a refusal that would have refused this defect |
| Tier | `control` (fails a gate), `warning` (reports and continues) or `documentation` (a person must read it). Record a `documentation` tier as a downgrade, with the reason that no stronger control was available |
| Covers | The observed defect and related call paths established by evidence |
| Branch not taken | One line |

Deliver the smallest effective code fix and regression or control within the approved scope. When a catalog or policy change is necessary for that outcome or separately authorized, edit its YAML source and run the applicable catalog and projection checks. Record other improvements as separate recommendations.

For a worked chain from signal to control, read [example](references/example.md).