Engineering

Reproduce Software Bugs — Bug Report to Reliable Repro

Support says it happens; nobody can make it happen. Turn a vague bug report — symptoms, environment, expected vs actual — into a reproduction strategy.

Overview

A bug you can't reproduce is a bug you can't honestly fix. This setup starts from exactly what support tickets provide — the structured bug report fields: symptoms, environment, expected behavior, actual behavior — and no reproduction steps. The contract's honesty mechanism takes over: instead of pretending a repro exists, stage three becomes INFORMATION NEEDED TO REPRODUCE, demanding the missing specifics — which users, what state, what sequence — and the investigation works the occurrence pattern until the bug can be summoned on demand. Only then does diagnosis begin.

Workflow

Feed the report as-is
Symptoms, environment, expected vs actual — the bug report structure IS the investigation input.
Let the contract demand specifics
INFORMATION NEEDED TO REPRODUCE lists the questions for support: which users, what state, what sequence.
Reduce before diagnosing
Once it reproduces, shrink to the minimal failing case — diagnosis on a minimal repro is half done.

Why This Works

The no-fabrication rule stops the model from inventing steps that mislead the whole investigation
Bug-report fields map one-to-one onto investigation inputs — nothing support knows gets lost
Pattern-first reproduction works even when steps are unknowable from the report

Best for

Bugs reported by users that no developer has seen
Support-to-engineering handoffs that lose detail
Teams whose bug reports say "sometimes it breaks"

Not for

Bugs that already reproduce — load the standard debugging setup and diagnose
Writing the regression test after reproduction — that's the Test Case Prompt Generator

Use cases

Converting support tickets into reproducible bugs
Listing exactly what is needed before diagnosis can start
Reducing a flaky repro to its minimal failing case

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
Build a reliable reproduction for the cart-emptying bug reported by support.
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: High.
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: Support reports carts occasionally empty themselves after login.
Expected behavior: Cart contents survive login.
Actual behavior: Cart is empty after login for some users; support has 14 reports this week.
Reproduction steps: none provided (a fact — see the framework below).
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. INFORMATION NEEDED TO REPRODUCE — no reproduction steps were provided: list exactly what is needed to reproduce this problem before diagnosing further. Do not pretend a reproduction exists.
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.

Used in Playbooks

Complete workflows that include this resource as a step.

AI Debugging Workflow Workflow · 5 steps

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

Explore all resources