--- name: root-cause-analysis description: >- Identify and confirm the cause of a defect from errors, logs, failing checks or reproduction evidence without implementing a fix. Use when the user asks why a failure happens or the cause is still uncertain; use bug-investigation when a verified fix is expected. --- # Root cause analysis ## When to use Whenever something behaves differently from what is expected and the cause is not yet proven. Use it before writing a fix, not after the first fix fails. It is the reasoning step inside `bug-investigation` and incident work. ## Required context The raw failure: error messages, stack traces, logs, the failing test output, or exact reproduction steps. If none is available, ask for it before theorizing. ## Preconditions The expected behavior is known. If it is ambiguous, confirm it with a human first; otherwise the "bug" may be a requirements question. ## Procedure 1. **Reproduce.** Turn the report into the smallest reliable reproduction: ideally a failing automated test, otherwise exact steps with observed output. 2. **Read the evidence literally.** Start from the actual error and location, not from a guess about what is probably wrong. 3. **Trace backwards** from the symptom to the first point where state diverges from expectation. Read the code on that path. 4. **Form one hypothesis at a time** and test it with an observation (a log line, a debugger, an assertion). Discard hypotheses the observation contradicts. When the observation must come from a running system, use `runtime-debugging`. 5. **Confirm the cause** by showing that changing only that cause changes the outcome. 6. **Check whether the same cause** affects other places with the same pattern. 7. Report the cause, the confirming observation and the reproduction. The fix and its regression test belong to the calling skill. ## Tools `core.repository.diff` against the last known-good revision when the defect is a regression; `core.repository.history`, when available, to narrow down which change introduced it. ## Rules `core.quality.unknowns-stay-unknown`: say "not yet known" rather than presenting a hypothesis as the cause. ## Verification Required: `unit` — the reproduction as a failing test, where the cause allows it. Recommended: `integration` or `runtime` when the defect only appears there. ## Evidence The reproduction (test or steps) and the observations that confirmed the cause. ## Completion criteria - A reliable reproduction exists. - The cause is explained in terms of the code, with the observation that confirms it. - Other occurrences of the same cause are listed or ruled out. ## Failure modes | Failure | Signal | Response | |---|---|---| | Fixing the symptom | The explanation does not say why the state diverged | Keep tracing upstream | | Theory without data | Hypotheses are not tied to an observation | Collect raw output first | | Two failed fixes | A second fix attempt failed | Stop; re-read the code path top-down and restate the mental model | ## References None. ## Paved integration Use the project-local Paved contract as the source of truth. Discover state with `node "/scripts/paved.mjs" status --json`, load only relevant `.paved/project/` context, and invoke verification with `node "/scripts/paved.mjs" verify --json`. `` is the installed Paved plugin directory, two directories above this SKILL.md. Always run the launcher from the repository being worked on, never from the plugin directory. Do not edit generated integration files or bypass Paved lifecycle and ownership checks.