AI Prompt for Systematic Debugging

What it does

Turns a vague bug report into a structured diagnosis. Forces reproduction before hypothesis, categorizes possible causes across five domains (data, timing, environment, logic, integration), and uses bisection tests to cut the search space in half each round. Three modes let you choose pure diagnosis, a teaching walkthrough, or pair-debugging that does both.

The Prompt

Help me debug this issue systematically. Don't guess — diagnose.

Bug report:
- What happens: [DESCRIBE THE BROKEN BEHAVIOR]
- What should happen: [DESCRIBE THE EXPECTED BEHAVIOR]
- When it started: [deploy, config change, dependency update, "always"]
- Frequency: [EVERY TIME / INTERMITTENT / ONLY UNDER SPECIFIC CONDITIONS]

Environment:
[LANGUAGE, FRAMEWORK, VERSION, OS — whatever's relevant]

What I've already tried:
[LIST WHAT YOU'VE CHECKED OR RULED OUT — "nothing yet" is a valid answer]

Mode:
- Solve — walk me through diagnosis to fix, minimal explanation
- Teach — explain your reasoning at each step so I learn the method, not just the answer
- Pair — diagnose AND teach as we go

[CHOOSE ONE OR DEFAULT TO "Pair"]

Process:

1. REPRODUCE — Can we trigger this reliably? If not, define the reproduction conditions
   we need before proceeding. If the bug is intermittent, identify what varies between
   "works" and "doesn't work." A bug you can't reproduce is a bug you can't verify you've fixed.

2. OBSERVE — Summarize the symptoms precisely. Separate what you KNOW from what you
   ASSUME. Name the exact boundary where behavior diverges from expectation.

3. HYPOTHESIZE — List 3-5 possible root causes TOTAL (not per category). For each one:
   - State the hypothesis in one sentence
   - Tag it with exactly ONE category: data/state | timing/concurrency |
     environment/config | logic | integration/contract
   - Explain WHY it would produce these specific symptoms
   - State what we'd expect to see IF this is the cause, and what we'd expect IF it's not
   - Rank by likelihood given the evidence

4. TEST — For the top hypothesis, suggest ONE diagnostic test that would confirm or
   eliminate it. The best test bisects the problem: it cuts the remaining search space
   roughly in half regardless of the result. Tie the test to the IF/IF-not expectations
   from step 3 — the outcome should be unambiguous.

5. ITERATE — When I give you the test result, update your hypothesis ranking and
   suggest the next test. Continue until we've isolated the root cause.

6. FIX — Only after the root cause is confirmed: propose the minimal fix, explain why
   it addresses the root cause specifically, and suggest a verification test that would
   catch a regression.

Rules:
- Do NOT suggest a fix before we've confirmed the root cause through testing. "Try this
  and see if it works" is not debugging — it's guessing
- Do NOT assume the bug is where the error appears. Stack traces point to where it
  crashed, not necessarily where it broke
- Do NOT blame the most recent change by default. Recency bias is the most common
  misdiagnosis — the newest code is the easiest suspect, not the most likely one
- Do NOT suggest rewriting entire functions or modules as a "fix." If you can't explain
  what specific line or condition causes the bug, you haven't diagnosed it yet
- Do NOT skip reproduction. If we can't reproduce it reliably, we can't verify the fix.
  "Works on my machine" is not resolution
- If the bug report above is too vague to form a hypothesis, say what's missing before
  proceeding. Incomplete inputs produce incomplete diagnoses

Mode-specific additions:

- Teach mode: before HYPOTHESIZE, state one framing heuristic the user should carry into
  this class of bug (e.g., "when a bug is intermittent, check shared mutable state before
  logic errors"). At each test, add a "Why this test?" line explaining what you'd conclude
  from each possible outcome.

- Pair mode: at each test, add a "Why this test?" line. After the fix, surface one
  "Debugging instinct" — a transferable heuristic earned from this specific session, in
  one sentence.

- Solve mode: skip framing and instinct lines. Be terse.

Usage Notes

• The core constraint is “do NOT suggest a fix until the root cause is confirmed.” This prevents the shotgun failure mode where AI suggests ten things to try at once.
• Feed test results back iteratively. The best debugging sessions are 3-5 rounds of hypothesize → test → refine.
• Categorizing hypotheses across five domains (data/timing/environment/logic/integration) forces the model to widen its search rather than listing five variations of the same logic error.
• Bisection is the single most valuable debugging concept to internalize: each test should cut the remaining search space roughly in half.
• Pair mode is the default because it mirrors how senior engineers actually debug with teammates — solve the problem and transfer the reasoning.
• For performance bugs, add “Include timing/profiling commands in your diagnostic tests” to the environment block.