Root-Cause Debugger
Stop guessing at fixes — isolate the actual cause of a bug step by step.
A systematic debugging prompt that forces the model to form hypotheses, rank them by likelihood, and propose the cheapest experiment to falsify each one — instead of pattern-matching a plausible-looking fix that doesn't address the real cause.
The prompt
Variables to fill in: {{bug_description}}{{environment}}{{attempts}}
You are an expert debugger. I will describe a bug. Your job is to find the ROOT CAUSE before proposing any fix.
Process:
1. Restate the symptom precisely: what happens, what was expected, and when it started.
2. List the 3–5 most plausible hypotheses, ranked by likelihood, each with the mechanism that would produce this exact symptom.
3. For each hypothesis, give the single cheapest check that would confirm or rule it out (a log line, a query, a curl command).
4. Ask me for any missing information you need. Do not propose a fix until a hypothesis is confirmed.
Bug description:
{{bug_description}}
Environment / stack:
{{environment}}
What I've already tried:
{{attempts}}How to use
- 1Describe the symptom exactly — include error messages verbatim, not paraphrased.
- 2List what you've already ruled out in {{attempts}} so the model doesn't repeat it.
- 3Run the checks it suggests and paste the results back; the conversation converges in 2–3 rounds.
- 4Only accept a fix once a hypothesis has been confirmed by evidence.
Examples
Intermittent 502s after deploy
Input
Bug: ~2% of requests return 502 since yesterday's deploy. Environment: Node behind nginx on k8s. Tried: rolling back nginx config (no change).
Output
Hypotheses: (1) New deploy lowered keep-alive timeout below nginx's upstream timeout — classic 502 mechanism, check `keepAliveTimeout` in the diff... (2) Pod memory limit causing OOM kills, check `kubectl get events`... Cheapest check first: grep the deploy diff for timeout changes.
Pro tips
- Paste stack traces in full. Truncated traces are the #1 cause of bad hypotheses.
- If it converges on 'race condition' immediately, push back and ask for the specific interleaving.
Frequently asked questions
Why does it ask questions instead of just giving a fix?+
That's the point of the prompt. LLMs eagerly propose plausible fixes that don't address the real cause. Forcing hypothesis-testing first is what makes the eventual fix trustworthy.
Does this work for non-code bugs, like data pipeline issues?+
Yes — the hypothesis-and-cheapest-check structure works for any system: data pipelines, infra, even spreadsheet formulas. Just describe the environment accurately.