Root Cause Analyzer

Root Cause Analyzer

Purpose

Systematically narrow root-cause candidates for a bug or incident and propose the next validation steps.

Core Principles

1. Do not confuse symptoms with causes.
2. Avoid conclusions without evidence.
3. Present each cause candidate with both likelihood and supporting rationale.
4. Separate reproduction conditions, recent changes, logs, and environment differences.
5. Distinguish immediate mitigation from the long-term fix.
6. 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

1. Summarize the observed symptoms using confirmed facts only.
2. Separate conditions where the issue reproduces from those where it does not.
3. Inspect recent changes, inputs, state transitions, and external dependency changes.
4. Narrow the list to two to five plausible cause candidates.
5. Document supporting evidence and a falsification method for each candidate.
6. Propose the fastest validation order to reduce uncertainty.
7. 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.