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.

Open in Debugging Prompt Generator

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.

How to use this resource

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

FAQ

Why does the debugging prompt refuse to just tell me the fix?

A stated rule blocks it: "Do not jump directly to a solution before identifying the most likely root cause." The ten-stage framework runs symptoms through root cause analysis first, and stage 9 requires any fix to carry its likely cause, supporting evidence, the change, and how to verify it, so you get "here is why this is likely the fix" rather than an unexplained patch.

What stops the AI from locking onto the first cause it thinks of?

The ROOT CAUSE RULES require the most likely cause plus at least two ALTERNATIVE causes, each carrying its supporting and contradicting evidence, and the EVIDENCE RULES say to carry at least two hypotheses until evidence separates them. The generated prompt enforces this in your own assistant; it structures the reasoning but can't guarantee the real cause is among them.

What is the FACT / ASSUMPTION / HYPOTHESIS labeling actually for?

It stops the silent promotion that derails investigations: every statement must be tagged a FACT (directly observed), an ASSUMPTION (believed without evidence, to be verified or discarded), or a HYPOTHESIS (a testable claim that ships with its test). An assumption can never quietly become a fact, which is the discipline the invoice-totals example is built to demonstrate.

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
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.

More resources from Debugging Prompt Generator

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

Resource

Debug a Production Incident

Stabilize, then diagnose: impact first, rollback options before intervention, timeline from the deploy history — forensic discipline under fire.

Operations

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

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