| name | root-cause-analyzer |
| description | Organize root-cause candidates and propose a validation order from symptoms, logs, reproduction steps, and recent changes. Use it when you need to narrow a bug or incident quickly. |
Root Cause Analyzer
Purpose
Systematically narrow root-cause candidates for a bug or incident and propose the next validation steps.
Core Principles
- Do not confuse symptoms with causes.
- Avoid conclusions without evidence.
- Present each cause candidate with both likelihood and supporting rationale.
- Separate reproduction conditions, recent changes, logs, and environment differences.
- Distinguish immediate mitigation from the long-term fix.
- Prioritize checks that yield the most information for the least cost.
Inputs
- Error symptoms or user report
- Reproduction steps
- Logs, error messages, or stack traces
- Recent changes or related diffs
- Environment details such as local, staging, or production
Workflow
- Summarize the observed symptoms using confirmed facts only.
- Separate conditions where the issue reproduces from those where it does not.
- Inspect recent changes, inputs, state transitions, and external dependency changes.
- Narrow the list to two to five plausible cause candidates.
- Document supporting evidence and a falsification method for each candidate.
- Propose the fastest validation order to reduce uncertainty.
- If helpful, separate temporary mitigation from the long-term fix direction.
Output Format
Symptom Summary
- What has been observed
- Impact scope
Reproduction Details
- Reproduction steps
- Conditions where it reproduces
- Conditions that remain uncertain
Cause Candidates
- Candidate 1
- Supporting evidence
- How to disprove or confirm it
- Candidate 2
- Supporting evidence
- How to disprove or confirm it
Validation Order
- Logs, code paths, or config to inspect first
- Expected observations
Temporary Mitigation
- Ways to reduce user impact
- Operational workarounds
Long-Term Fix Direction
- Areas to modify once the root cause is confirmed
- Tests or regression protection to add
Remaining Uncertainty
- Additional information needed
- Follow-up questions
When Information Is Missing
- Keep confirmed facts and hypotheses clearly separated.
- Limit the cause-candidate list to five.
- Limit follow-up questions to three.
