Engineering

Root Cause Analysis Prompt

Forensic-grade RCA: most likely cause plus alternatives, each with supporting AND contradicting evidence — and unknowns that stay unknown.

Overview

Root cause analysis fails when it stops at the first plausible story. This setup runs the forensic mode on a duplicated-notifications problem with no reproduction yet: every conclusion must cite the specific evidence supporting it, at least two alternative causes carried alongside the leading one, contradicting evidence listed as diligently as supporting evidence, and — the forensic signature — assumptions forbidden in conclusions entirely, allowed only as questions in MISSING INFORMATION. With no repro provided, the contract demands the information needed to build one instead of pretending.

Workflow

Demand the alternatives
The rules require at least two alternative causes — the leading story has to beat real competitors.
Weigh contradictions equally
Evidence against each candidate is listed next to evidence for it — the column most RCAs quietly omit.
Let unknowns stand
"Insufficient evidence" is a legitimate finding; a plausible guess in its place is how wrong RCAs get written.

Why This Works

Competing hypotheses prevent narrative lock-in on the first story
Contradicting-evidence discipline surfaces the inconvenient data early
Forensic assumption rules make the final document trustworthy by construction

Best for

Bugs with multiple plausible stories and real stakes
Engineering cultures that write blameless post-mortems
Investigations that feed permanent fixes, not patches

Not for

Quick local bugs — Fast or Standard mode resolves them with less ceremony
Incident response while the fire burns — that's the production incident setup; RCA comes after stability

Use cases

RCAs that will be read by people who weren't there
Problems where the obvious cause already proved wrong
Post-incident analysis that has to survive scrutiny

Customize This Resource

Opens this setup in Debugging Prompt Generator. Generate to get the full investigation contract — then adjust the problem type, mode, and environment.

Open in Debugging Prompt Generator

Prompt Template

DEBUGGING OBJECTIVE
Run a rigorous root cause analysis on the duplicated notification emails.
Problem type: functional bug — the code runs without error but produces the wrong result.
Determine what is actually happening. Do not jump directly to a solution before identifying the most likely root cause.

SYSTEM CONTEXT
Environment: staging — verify parity with production configuration; any difference from production is itself a suspect.
Reported severity: High.
Investigation strategy for this problem type:
- The bug lives in logic, not plumbing: compare implemented logic against intended behavior step by step.
- Name the exact step where implementation and intent diverge — "somewhere in the calculation" is not a finding.
- Hunt incorrect assumptions: about input shape, ordering, time zones, rounding, and state.

KNOWN FACTS
Symptoms: Some customers received the same notification email two or three times.
Expected behavior: Exactly one email per notification event.
Actual behavior: Duplicates observed for roughly 2% of events on busy days.
Reproduction steps: none provided (a fact — see the framework below).
Logs / errors: none provided.

INVESTIGATION FRAMEWORK
Structure the investigation in exactly these stages:
1. SYMPTOMS — restate the observable symptoms, separating observations from interpretations.
2. KNOWN FACTS — list what is directly evidenced, each fact with its source.
3. INFORMATION NEEDED TO REPRODUCE — no reproduction steps were provided: list exactly what is needed to reproduce this problem before diagnosing further. Do not pretend a reproduction exists.
4. POSSIBLE CAUSES — candidate causes, drawn from the checklist below and from the evidence.
5. ROOT CAUSE ANALYSIS — the most likely cause and the alternatives, per the root cause rules.
6. EVIDENCE REVIEW — which evidence is solid, which is weak, which is missing, and what contradicts what.
7. MISSING INFORMATION — what you need that you do not have. Ask for it; do not guess it.
8. VALIDATION PLAN — the tests or observations that will confirm or eliminate the leading cause.
9. FIX RECOMMENDATION — per the fix requirements below.
10. POST-FIX VERIFICATION — per the verification requirements below.

DEBUGGING CHECKLIST
Candidate causes to check for this problem type:
1. Business rules implemented differently than specified
2. Missing conditions — the unhandled case that takes the wrong branch
3. Boundary conditions decided the wrong way (< vs <=, inclusive vs exclusive)
4. Wrong data transformations: rounding, truncation, encoding, unit conversion
5. Stale or cached values used where fresh ones were intended
6. Order-of-operations errors in calculations or state updates

ROOT CAUSE RULES
- Identify the MOST LIKELY root cause — and at least two ALTERNATIVE causes.
- For each candidate cause: list the evidence supporting it AND the evidence contradicting it.
- Define a validation step for each candidate: what observation would confirm or eliminate it.
- The symptom site and the cause site may be different places — finding where it hurts is not finding why.

EVIDENCE RULES
Label every statement as exactly one of:
- FACT: directly observed. Example: "The application returned HTTP 500."
- ASSUMPTION: believed without direct evidence. Example: "The database is probably down." Assumptions must be verified or discarded — never silently promoted to facts.
- HYPOTHESIS: a testable causal claim. Example: "A failed database connection may be causing the 500 response." Every hypothesis comes with its test.
- Every conclusion must cite the specific evidence that supports it — quote the log line, the stack frame, the reproduction result.
- Unknowns remain unknown: write "insufficient evidence" rather than a plausible guess.
- No unsupported certainty: every claim carries its confidence level and its evidence.
- Treat the absence of expected evidence as a finding in itself.
- Assumptions are forbidden in conclusions — they may appear only in MISSING INFORMATION, as questions to resolve.

VALIDATION REQUIREMENTS
- Before proposing any fix, state how the diagnosis was validated — or what validation is still pending.
- The gold standard: a reproduction that turns the failure on and off by toggling the suspected cause.
- If the root cause cannot be validated with the available information, say so and list what is needed.

FIX REQUIREMENTS
- Any fix proposal must include: the likely cause, the supporting evidence, the proposed change, and how to verify it worked.
- Frame it as "here is why this is likely the fix" — never an unexplained patch.
- Prefer the smallest fix that addresses the root cause; label symptom-only fixes as temporary mitigations.

POST-FIX VERIFICATION
- Define what to observe after the fix: the original reproduction passing, error rates at baseline, the affected metric recovered.
- Check for regressions in the paths the fix touched.
- State how long to observe before declaring the problem resolved — intermittent problems need longer windows.

Related Resources

Explore more resources that work well with this one.

Used in Playbooks

Complete workflows that include this resource as a step.

AI Debugging Workflow Workflow · 5 steps

Tip: Save time by exploring related resources and tools that integrate with this workflow.

Explore all resources