Implementation worksheet · 6 min read
A Bug Report Template an AI Coding Agent Can Act On
Seven fields: the exact steps from a known starting state, what you expected, what happened instead, the error text verbatim rather than described, where it happened (URL or screen, environment, account state), how often it reproduces out of how many attempts, and — the field people omit — what must not change as a result of the fix. That last one is what prevents a plausible repair that quietly breaks a working feature. The single most damaging line in a bug report is a guess at the cause stated as fact, because an agent will take it as a constraint and fix the thing you named rather than the thing that is broken.
Describing a bug to a coding agent has the same failure mode as describing it to a contractor who cannot see your screen: they will act confidently on whatever you gave them. The difference is that an agent will not stop to ask, so a vague report produces a confident change rather than a question, and you find out at review time or later.
Put it into practice
1. Start from a known state, not from where you happened to be
'Log in as a free-tier account with no projects, click New Project' is reproducible. 'Go to the dashboard' assumes whatever state your session was in. Most reports that cannot be reproduced fail here rather than on the steps themselves.
2. Paste the error verbatim
The full message, the stack trace if you have one, the console output, the network response. Not a paraphrase. 'It says something about a token' loses the exact thing that identifies the code path. If the error is only visible in a log, go and get it — this is the highest-value field on the list.
3. Separate expected from actual, as two sentences
Written separately they expose disagreements about intended behaviour, which is a surprising share of reported bugs. Written as one sentence — 'it should work but it does not' — they hide it, and you get a fix for something that was behaving as designed.
4. State the reproduction rate honestly
'Every time, 5 of 5' and 'once, out of about ten attempts' lead to completely different investigations. Intermittent bugs need timing, state or ordering explanations; deterministic ones do not. Guessing 'sometimes' when you have tried twice wastes the effort on the wrong class of cause.
5. List what must not change
The features around the bug that currently work. This is the field that prevents collateral damage — an agent scoped to 'fix the signup error' with no invariants may restructure the auth flow and break password reset. Name the flows that must still pass.
6. Do not state a cause as fact
If you have a hypothesis, mark it as one: 'possibly related to the caching change yesterday, unverified'. Stated as fact, it becomes the constraint the fix is built around, and a wrong guess produces a confident fix to a working component while the real bug survives.
7. Say how you will verify the fix
The same steps, the expected result, and the neighbouring flows you will re-check. Writing this before the fix means the verification is not invented afterwards by someone who already believes it works.
The bug report template
Copy this structure into your review document and record your observed result for each row.
| Field | Your entry | Why it matters |
|---|---|---|
| Starting state | reproducibility | |
| Exact steps | the fix target | |
| Expected | exposes design disagreements | |
| Actual | the observed defect | |
| Error text, verbatim | identifies the code path | |
| Where: URL/screen, environment, account | narrows the surface | |
| Reproduction rate (n of m) | deterministic vs intermittent | |
| Must not change | prevents collateral damage | |
| Hypothesis, marked as unverified | stops a guess becoming a constraint | |
| How the fix will be verified | written before, not after |
A failure worth checking
The confident guess. The report says 'this is because the session cache is not clearing' — a reasonable-sounding hypothesis from someone who saw a related issue last month. The agent takes it as the requirement, rewrites cache invalidation, and the change is plausible, passes review, and does not fix the bug, which was a timezone comparison two files away. Now there is a cache change nobody needed, in the codebase, unexplained. Marking the hypothesis as unverified costs two words.
Common questions
How much detail is too much?
Rarely a problem in practice — the usual failure is far too little. What does hurt is irrelevant detail presented as relevant, particularly speculation about the cause. Be exhaustive about observation and restrained about explanation.
What if I cannot reproduce it?
Say so explicitly and give everything you have: timestamps, the affected account, what they were doing, any error from logs. An honest 'reported once by a customer, not reproduced' leads to an investigation. Pretending it reproduces leads to a fix for a guessed scenario.
Basis and scope
This is a proposed implementation method using illustrative examples, not a measured benchmark or a customer case study. Prepared with AI assistance. Validate product-specific behavior against current documentation and your own test environment.