Engineering

Root Cause Analysis Prompt

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

Open in Debugging Prompt Generator

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.

How to use this resource

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

FAQ

How does this RCA prompt stop the AI from locking onto the first plausible cause?

The ROOT CAUSE RULES require the most likely cause plus at least two alternative causes, and for each candidate you get supporting AND contradicting evidence side by side. Assumptions are forbidden in conclusions — they may appear only in the MISSING INFORMATION stage as questions to resolve. The debugging-prompt-generator produces this prompt; the diagnosis is still a hypothesis you validate.

How does this prompt handle a bug with no reproduction steps yet?

Stage 3, INFORMATION NEEDED TO REPRODUCE, handles exactly this: the loaded duplicated-emails case provides no reproduction steps, so the framework lists what's needed to reproduce before diagnosing further and says "Do not pretend a reproduction exists." The output tells you what to gather; it can't confirm the cause without it.

Is this overkill for a quick local bug I just want fixed?

Likely yes. This runs the full 10-stage framework — SYMPTOMS through POST-FIX VERIFICATION — with FACT/ASSUMPTION/HYPOTHESIS labeling on every statement, built for RCAs read by people who weren't there. notFor says quick local bugs are better served by Fast or Standard mode in the debugging-prompt-generator, which resolves them with less ceremony.

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

Copy it as-is, or use Open in Debugging Prompt Generator to load it pre-filled and customize it with your own context.

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.

More resources from Debugging Prompt Generator

Resource

Debugging Prompt — the Investigation Contract

"Fix this error" gets guesses. The investigation contract gets a ten-stage diagnosis: facts separated from assumptions, alternatives weighed, fixes justified.

Prompt Engineering

Resource

Error Analysis Prompt

An exception is a symptom, not a diagnosis: trace from the throw site back to the root trigger, with the runtime checklist on the table.

Engineering

Resource

Debug Performance Problems

Measure before reasoning: find WHERE the time goes, separate latency from memory from throughput, and think at production scale.

Engineering

Resources that pair well

Resource

Code Review Prompt — the Review Contract

"Review this code" gets shallow comments. The review contract gets findings with severities, a checklist, and a verdict.

Prompt Engineering

Resource

Playwright Test Prompt

getByRole over CSS chains, auto-wait over sleep, web-first assertions — Playwright tests written the way Playwright wants.

Engineering

Resource

Refactor Prompt — the Behavior Preservation Contract

"Refactor this code" invites silent behavior changes. The refactoring contract preserves business rules, outputs, and side effects — and flags uncertainty instead of deciding it.

Prompt Engineering

Related tools

Tool

Debugging Prompt Generator

Build debugging prompts from symptoms, environment, and reproduction steps — root cause first, fix second.

Coding Workflows

Workflows that use this resource

Workflow

AI Debugging Workflow

The order that actually finds bugs instead of guessing at them — so you end with a verified fix, not a plausible one that quietly returns next week.

5 steps 20–40 minutes

Guides for this resource

Guide

Get AI to Debug Without Chasing the Wrong Cause

Paste an error, say "fix this," and AI patches the first thing it sees — the symptom clears, the real cause stays. Here's how to run a debugging pass that works from symptoms and evidence to a root cause, and holds off on a fix until the evidence points at one.

Software Development with AI

Guide

How to Write an Incident Postmortem With AI

The incident's over and you've got a channel full of messages and logs, so "summarize this" returns a blamey story with an invented root cause. Here's how to turn your real notes into a blameless incident postmortem: confirmed timeline, evidence-backed factors, owned actions.

Software Development with AI

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