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
- 参考文档skill.yaml443 B
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
- Reproduce. Turn the report into the smallest reliable reproduction: ideally a failing automated test, otherwise exact steps with observed output.
- Read the evidence literally. Start from the actual error and location, not from a guess about what is probably wrong.
- Trace backwards from the symptom to the first point where state diverges from expectation. Read the code on that path.
- 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. - Confirm the cause by showing that changing only that cause changes the outcome.
- Check whether the same cause affects other places with the same pattern.
- 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
sample-skill
Does a sample task. Use when a sample is needed.
unexplained-contract
Does a sample task. Use when a sample is needed.
shell-block
Does a sample task. Use when a sample is needed.
project-identifier
Does a sample task. Use when a sample is needed.
oversized
Does a sample task. Use when a sample is needed.
no-activation
Does a sample task.