The failure was reproduced before any application code changed.
Coding
Reproduce a bug before fixing it
Make the agent write the failing test first, isolate the smallest cause and only then patch — with the command that proves it.
You are fixing a bug. Do not edit application code until step 4.
Inputs:
- Error output: [ERROR]
- Repository and relevant paths: [REPO]
- Command that fails: [COMMAND]
- Runtime and environment: [ENV]
Work in this order:
1. Restate the expected behaviour and the actual behaviour in one sentence each.
2. Find the smallest command or test that reproduces the failure. Record the exact command and the exact output.
3. Write a failing test that would pass if the bug were fixed. Run it. Paste the failure.
4. Isolate the root cause. Name the file, the function and the line. Explain why the failure happens, not just where it appears.
5. Propose the smallest patch that fixes the cause. Do not refactor unrelated code.
6. Run the failing test and the original command. Paste both results.
7. Report: symptom, reproduction, root cause, patch, proof, residual risk.
Rules:
- Never change a test to make it pass. If the test is wrong, say so and explain why.
- If you cannot reproduce the failure, stop and list what you need. Do not guess a fix.
- Do not touch secrets, credentials or production data.
- Do not add a dependency unless the fix requires it and you explain why.
| Variable | What to put there |
|---|---|
[ERROR] | The complete trace, including the command and the first lines of output. A single error line often hides the trigger. |
[REPO] | The repository and the paths the agent may read. Keep the blast radius explicit. |
[COMMAND] | The exact command that fails, with flags and environment variables. “Run the tests” is not a reproduction. |
[ENV] | Runtime version, OS, package manager and any relevant service version. A bug that only appears on one version is a different bug. |
Run it
How to use this template
Give the agent the full trace and the exact command. Reproduce it yourself once before delegating.
Require the failing test before the patch. A fix without a test is a hypothesis.
Run the same command after the patch and compare the output. Do not accept “should work now”.
Commit the test and the patch together. The test is the evidence; the patch is the change.
Checks
Guardrails before you trust the output
The test fails before the patch and passes after it.
No test was edited to make the suite green.
Secrets and production data were not read or written.
Adapt
Variations worth keeping
If the bug is intermittent
Add: “Repeat the reproduction at least 20 times and report the failure rate. If the rate is below 1 in 20, say so and propose an instrumented reproduction rather than a patch.”
If the bug is in a dependency
Add: “Identify the smallest version range that reproduces the issue and the upstream issue or changelog entry. Do not patch vendored code unless there is no supported fix.”
Why this works
The most expensive coding-agent failure is not a wrong patch. It is a plausible patch applied to a problem the agent never reproduced. The test comes first because it turns “it seems fixed” into a claim with evidence.
The prompt also separates root cause from symptom. A model can spend a long time editing the line where the exception is raised when the actual cause is three calls away.
What good looks like
The reproduction is one command, and it fails in a way a reader can recognize. The test is small enough to read and specific enough that it would fail again if the bug returned. The patch touches the cause, not the neighbourhood.
If the agent cannot reproduce the bug, a good answer is “I need X”. That is a successful run, not a failure.
Adapt it to your work
For a frontend bug, add the browser, viewport and a screenshot. For a data bug, add a small fixture that reproduces the wrong aggregate. For a CI-only failure, add the CI image tag and the environment variables that differ from local.
Failure modes
- The agent “fixes” the test. Reject any change to the test before the patch; it is evidence tampering.
- The patch is a rewrite. Ask for the smallest diff and a separate follow-up for cleanup.
- The root cause is “a race condition”. Ask for the two events, their order and the line that observes the order. “Race condition” is a category, not a cause.
Related templates
This page is part of the free library.
The prompt is also in the Markdown mirror at
/prompts/reproduce-a-bug.md. If the scenario is close but not right, send the gap to the help desk with the output you expected.
Found a gap in the library?
Send the scenario, the prompt that failed, or the harness change that broke your setup. The help desk takes questions and corrections from humans and agents, and every accepted fix updates the page date.