Prompt Engineering

Debugging with AI — Done Right

AI is a strong debugging partner and a confident wrong one: the fast-investigation contract that keeps its speed and removes its overconfidence.

Overview

AI debugging help fails in a characteristic way: instant, confident, plausible — and anchored on the first theory it likes. This setup is the everyday counter: a fast investigation (assumptions allowed, but labeled) on a typical timezone-shaped date filtering bug, with the rules that domesticate the model's confidence — name the most likely cause AND what would confirm or kill it, separate facts from assumptions even at speed, and never propose a fix without the validation step attached. Fast mode keeps debugging conversational; the contract keeps it honest.

Workflow

Stay fast, stay labeled
Fast mode allows assumptions — the contract just refuses to let them dress as facts.
Confirm or kill
Every "most likely cause" arrives with the observation that would confirm or eliminate it — usually a one-minute check.
Escalate modes when wrong
If the fast diagnosis misses, rerun in Standard or Forensic — same inputs, stricter evidence rules.

Why This Works

Labeled assumptions preserve speed while removing the silent-promotion failure mode
Confirm-or-kill steps convert confident theories into cheap experiments
Mode escalation gives the everyday workflow a rigor dial instead of a cliff

Best for

Developers already debugging in a chat window
Local bugs with cheap reproduction loops
Anyone burned by a confident wrong AI diagnosis

Not for

Production incidents — switch to the incident setup; speed without discipline is how outages extend
Bugs where being wrong is expensive — Forensic mode exists for those

Use cases

Everyday bugs where full forensics is overkill
Keeping AI's first theory from becoming the only theory
Quick diagnoses that still attach their validation step

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
Diagnose the broken date filtering on the orders page with AI assistance.
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: local development — full access to debugger, logs, and code; reproduce freely and instrument aggressively.
Reported severity: Low.
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: Filtering orders by date returns results outside the selected range.
Expected behavior: Only orders within the selected range appear.
Actual behavior: Orders from the next day appear in the results.
Reproduction steps:
- Filter orders for yesterday in a browser profile set to UTC+3
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. REPRODUCTION STEPS — verify the provided steps reproduce the problem; reduce them to the minimal failing case.
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.
- Move quickly: reasonable assumptions are allowed — but every assumption is labeled as one.
- Name the single most likely cause first, then state what would confirm or kill it.

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.