Prompt Engineering

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.

Overview

Most debugging prompts hand the model symptoms and hope. The investigation contract structures the work instead: a ten-stage framework from restated symptoms through root cause analysis to post-fix verification, with the discipline that separates senior debugging from guessing — every statement labeled FACT, ASSUMPTION, or HYPOTHESIS, every candidate cause carrying both its supporting and its contradicting evidence, and the core rule stated outright: do not jump to a solution before identifying the most likely root cause. This setup loads a classic wrong-calculation bug to show the full contract.

Workflow

Feed evidence, not conclusions
Symptoms, expected vs actual, repro steps, raw logs — the contract works from what is observed.
Hold the ten stages
Symptoms → facts → reproduction → causes → analysis → evidence → gaps → validation → fix → verification. No stage skipped.
Check the fix's pedigree
Stage nine requires cause + evidence + change + verification — "here is why this is likely the fix", never just a patch.

Why This Works

Structure prevents the jump-to-solution reflex that wastes debugging sessions
The fact/assumption split catches the silent promotion that derails investigations
Required alternatives stop the first plausible cause from ending the search

Best for

Developers using chat AIs as a debugging partner
Bugs where the first guess has already failed once
Teams standardizing how problems get investigated

Not for

Judging code quality with no failure present — that's the Code Review Prompt Generator
Writing the regression test after the fix — that's the Test Case Prompt Generator

Use cases

Getting a diagnosis instead of a guessed patch
Forcing alternatives before committing to a cause
Keeping assumptions labeled instead of silently promoted

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 why invoice totals are wrong for some customers since the last release.
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: shared development — check for collisions with other developers' changes and shared test data.
Reported severity: Medium.
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 invoices show totals a few cents higher than expected.
Expected behavior: Invoice total equals the sum of line items minus discounts.
Actual behavior: Totals differ by +0.01 to +0.04 on roughly 5% of invoices.
Reproduction steps:
- Create an invoice with three line items and a 10% discount
- Compare the computed total against a manual calculation
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.
- Prefer evidence over inference; where evidence is missing, label the assumption explicitly.
- Carry at least two hypotheses until evidence separates them.

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.