Prompt template
A debugging prompt that starts with evidence, not guesses.
This template turns a symptom, reproduction path, and available evidence into a ranked investigation plan. It is useful when an agent should diagnose first and avoid changing files before the cause is supported.
Reviewed September 22, 2026 · Templates and examples use fictitious data.
When to use this debugging prompt
Use it for a repeatable error, a regression after a change, an intermittent failure with partial logs, or a mismatch between expected and observed behavior. Start with the smallest reproducible symptom rather than asking an agent to “find the bug” across an entire system.
The template deliberately separates confirmed facts from hypotheses. That distinction makes the investigation easier to audit and reduces the chance that the first plausible explanation becomes an untested fix.
Reusable template
Error diagnosis prompt
# Investigate {{error}}
## Context
- Project: {{project}}
- Observed symptom: {{symptom}}
- Expected behavior: {{expected_behavior}}
- Reproduction steps: {{reproduction_steps}}
- Available evidence: {{evidence}}
- Recent relevant changes: {{recent_changes}}
<instructions>
Trace the execution path involved in the failure. Separate confirmed evidence from hypotheses and rank hypotheses by likelihood.
For each hypothesis, name the observation or test that would confirm or reject it. Prefer the smallest verifiable correction and explain its regression risk. Do not change files yet.
</instructions>
<output_format>
1. Confirmed facts
2. Ranked hypotheses
3. Investigation plan with concrete checks
4. Most likely root cause, if supported
5. Smallest proposed fix and validation plan
</output_format>What to collect before asking
{{error}}
A short name for the failure. Keep the exact message in the evidence field.
{{symptom}}
What actually happened, including frequency and the user-visible consequence.
{{expected_behavior}}
The observable result that should have happened instead.
{{reproduction_steps}}
The minimal ordered actions, inputs, environment, and timing needed to reproduce it.
{{evidence}}
Relevant logs, stack traces, screenshots, failing tests, or measured values with secrets removed.
{{recent_changes}}
Deployments, dependency upgrades, configuration changes, or migrations near the first occurrence.
Filled example
Error: Duplicate order after retry.
Project: Checkout API and payment webhook worker.
Observed symptom: About one in 200 timed-out checkouts creates two orders with the same payment reference.
Expected behavior: Retrying a timed-out request returns the original order.
Reproduction: Delay the database response beyond the client timeout, retry with the same idempotency key, then release both requests.
Evidence: Two inserts share the payment reference; only the second request logs an idempotency lookup miss.
Recent change: Idempotency lookup moved outside the database transaction.
The likely investigation should compare the lookup and insert transaction boundaries, verify the database constraint, and reproduce concurrent requests. “Add another retry” is not a supported answer unless evidence shows the retry policy is the cause.
A practical investigation loop
- Freeze the facts. Record the exact symptom and current evidence before changing the system.
- Reduce the reproduction. Remove unrelated services and steps until the failure still occurs.
- Rank hypotheses. Prefer explanations that account for all confirmed facts.
- Design a discriminating check. Each check should make at least one hypothesis more or less likely.
- Apply the smallest fix. Validate both the reproduction and neighboring behavior that could regress.
Limits
Remove credentials and personal data before sharing evidence with any external tool. If an agent cannot inspect the runtime, database, or repository, ask it to design checks rather than pretending it observed those systems.