AGENT SKILL

root-cause-analysis

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.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

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.

02 资源文件 1

03 SKILL.md 正文

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.

04 同仓库更多 Skills