Root Cause

---
name: root-cause
description: Evidence-driven debugging discipline. Use when investigating ANY bug, failure, crash, alert, flaky test, or unexpected behavior, before proposing or applying a fix. Enforces no-cause-no-fix - collect evidence, trace the full sequence, instrument when evidence is missing, prove the original and root cause (not the surface symptom), then fix and verify. Trigger on "why is X failing", "debug Y", "this error", "it crashes", "investigate Z", or any symptom that does not yet have a proven mechanism.
---

# Root Cause

A symptom is not a cause. An alert, a stack-trace line, an error email, a failing
build, a red test — each is *where the problem surfaced*, not *why it happened*.
This skill is the discipline that gets you from symptom to proven mechanism before
a single line of fix is written.

## The one rule everything serves

**NO CAUSE, NO FIX.** You are not allowed to propose, apply, or commit a fix until
you can explain the mechanism with evidence — 100%, no guessing. If you cannot yet
say *why* it happens, you are still investigating. Suppressing or silencing the
symptom is not a fix.

## The loop

Work these steps in order. Do not skip ahead — skipping is how surface fixes get
shipped and the real bug returns.

### 1. Reproduce / observe
- Establish the exact conditions under which the symptom appears. Inputs, state,
  environment, timing, which user/data/route.
- If you cannot reproduce, that is itself a finding — note what you tried and what
  would make it reproducible. Do not start guessing fixes for a bug you cannot see.

### 2. Collect evidence FIRST
- Read the actual code on the failing path. Read the actual logs. Query the actual
  data/state. Check official docs for the actual API behavior.
- Every claim about what the code or system does must come from something you read
  or ran this session — not memory, not assumption. Cite it (`file:line`, log line,
  query result, doc URL).
- Resist the first plausible story. The first explanation that "sounds right" is a
  hypothesis to test, not a conclusion.

### 3. Trace the sequence
- Follow the path from the ORIGINAL trigger forward to where the symptom surfaced.
  The failure point is usually downstream of the cause.
- Identify two distinct things:
  - **Original cause** — the first thing that went wrong (bad input, missing
    precondition, wrong config, an earlier write).
  - **Root cause** — the underlying reason that original cause was possible (the
    missing validation, the wrong default, the broken contract, the race).
- A fix at the surface (where it crashed) without addressing the root cause is a
  band-aid. Fix the root; verify the surface symptom disappears as a consequence.

### 4. Insufficient evidence -> INSTRUMENT, don't guess
When the evidence to date does not prove the mechanism:
- State explicitly what is missing ("I can't see the value of X at the point of
  failure", "I don't know which branch is taken").
- Then choose, in this order:
  1. **Ask** for the specific debug info, logs, or reproduction if the user/system
     can provide it.
  2. **Instrument** — add targeted debug loggers/markers at the RIGHT points in the
     code path (entry/exit of the suspect function, the branch condition, the value
     just before the failing operation). Place them to discriminate between
     competing hypotheses, not everywhere.
  3. Re-run, gather the data, read it.
- Never fill the evidence gap with speculation. Instrument and measure instead.
- Track temporary instrumentation so it is removed once the cause is proven (note it
  in your summary; if it must stay, say why).

### 5. Form and TEST the hypothesis
- State the hypothesis as a falsifiable claim: "If the cause is C, then changing/
  observing M will show R."
- Test it against the evidence. Try to REFUTE it, not just confirm it. If it
  survives, you have the cause. If not, return to step 2 with what you learned.
- Beware confirmation bias: one matching log line is not proof if another hypothesis
  predicts the same line.

### 6. Fix at the root, then verify
- **Fixing an anti-hall bug?** First run `node <plugin-root>/scripts/defect.js similar
  <symptom words> --component <module>` and read the past fixes for this component.
  If `defect.js recurring` lists it as a hotspot, fix the class, not the instance.
- Apply the minimal fix that addresses the proven root cause.
- Re-run the reproduction from step 1. Show the actual output proving the symptom is
  gone. "Should work now" is not verification — running it is.
- Add or update a test that would have caught this, so it cannot silently return.
- Remove temporary instrumentation (unless deliberately kept).

## Anti-patterns (stop if you catch yourself here)

- Proposing a fix in the same breath as first seeing the error.
- "It's probably X" followed by editing code, with no evidence for X.
- Catching/swallowing the exception, raising a timeout, adding a retry, or hiding the
  alert — to make the symptom go away without explaining it.
- Listing five possible causes instead of checking which one is real.
- Declaring it fixed without re-running the failing case.

## When the bug is large or spans resets

For multi-session or complex investigations, keep a running evidence log: the
symptom, what you have ruled OUT (with evidence), the current leading hypothesis, and
the next experiment. This survives context resets and stops you re-investigating the
same dead ends. (If `superpowers:systematic-debugging` is available, it pairs well
here; this skill is the evidence-and-cause spine, usable with or without it.)

## Relationship to the always-on hook

The plugin's `verify-first` hook injects a short version of this discipline into
every turn (no jumping to conclusions, no cause-no-fix, instrument-don't-guess).
This skill is the full protocol you invoke when you are actively hunting a specific
bug.