What belongs in a bug report depends on who reads it. For a human developer, a clear prose description is enough to start investigating. For a coding agent, the prose is almost irrelevant. The agent needs the console error, the failed network call, and the page state from when the bug happened.
The fields that matter are different. This is what a coding agent actually reads, and why "cannot reproduce" is a format problem, not a capability problem.
The six fields a coding agent needs
A bug report structured for agent consumption contains six things. Not all six are available on every bug, but the more of them you include, the more likely the agent can reproduce the failure without follow-up questions.
1. The error message, exact text
Not "something went wrong". The literal console error, with the full stack trace if one was thrown. An agent can search a codebase for an exact error string. It cannot search for a paraphrase.
2. The failed network call
The HTTP method, URL, status code, and response body. If a request returned 500, the agent knows the failure is server-side. If the response body contains a specific message, the agent knows where to look. The network tab in DevTools has this; the hard part is capturing it before the user closes the page.
3. The page URL and application state
Where was the user when the bug happened? A URL like /reports?range=q4&view=chart tells the agent which code paths were active. Without this, the agent has to guess which page state to reproduce.
4. The browser and OS
Not always relevant, but critical for layout bugs, permission errors, and rendering differences. "Chrome 125, macOS Sonoma" is one line. Without it, the agent cannot rule out environment factors.
5. Steps to reproduce
This is the one field that overlaps with a human-readable report. Numbered steps, starting from a known state, ending at the failure. The steps to reproduce generator formats these for you. One action per step; stop at the point where things go wrong.
6. What was expected versus what happened
Two separate fields. The expected result tells the agent what correct behaviour looks like, which is often what the code is supposed to do but does not. The actual result is what the user saw. Both together are a test case the agent can try to reproduce.
Why prose descriptions fail coding agents
The standard bug report format (a paragraph of prose describing what went wrong) is optimised for human readers who can fill in the gaps from memory, context, and experience. A developer reading "the export button isn't working on the reports page" can guess which code to look at, send a follow-up message, or reproduce it locally.
A coding agent cannot do any of those things. It works from evidence in its context window. When the report is a sentence, the agent produces a guess-fix or returns "cannot reproduce", and you lose the round-trip advantage of having an agent at all.
The console error and network call are the evidence half of the report. The prose description is the human-facing half. Most bug reports only have the human-facing half. That is why agents struggle.
Agents also cannot ask follow-up questions the way a developer can. When a developer needs the console output, they can send a message and ask. When a coding agent needs it, the information either exists in the report or it is gone. The best window to capture that evidence is at the moment the user clicks submit, before the page is closed, the tab is refreshed, and the console is cleared.
How to capture the right fields
There are two ways to get the right fields into every bug report.
Manual: a structured form
The bug report template generator produces a form covering all six fields above. You can embed it in a CONTRIBUTING.md, paste it into GitHub or Linear issue templates, or share it as a link. Users fill in what they have; the structured output goes into the issue body.
The limitation of manual capture is that users generally do not have the console output. Most users do not know how to open DevTools, and even developers sometimes close the tab before copying the error. The fields that are hardest to fill in manually are exactly the ones agents need most.
Automatic: a widget that captures context before submit
The Quell widget buffers the console, network requests, and page metadata continuously in the background. When the user clicks "Send feedback", the report already contains the last N console lines, the failed network calls, the page URL, and the viewport size, before the user has written a word.
The user writes the prose description. The widget provides the evidence half. The result is a report that covers all six fields without asking the user to open DevTools.
The /context endpoint then exports the full report as structured Markdown a coding agent can read directly. See how to give Claude Code access to user feedback for the setup, and the agents page for the full scope matrix.
What to skip
A few things appear in bug report templates but add noise for agents.
- <strong>Reproduction rate estimates</strong> ("it happens about 20% of the time") are useful for a human triaging severity but not for an agent trying to reproduce a specific failure. Skip them unless you are also including the conditions that affect the rate.
- <strong>User sentiment</strong> ("this is really frustrating") belongs in product feedback, not a bug report. It does not tell an agent anything actionable.
- <strong>Guessed root causes</strong> ("I think it might be a caching issue") can bias an agent toward a wrong hypothesis. Include the evidence; leave the diagnosis to the agent. A report that says "TypeError at reports.js:284" does not need to also say "I think the map function is receiving null."
- <strong>Unannotated screenshots</strong> are less useful than a screenshot with the broken element circled. An agent cannot focus on the right detail without guidance. Annotate or skip it.
Frequently asked questions
What is the most important thing to include in a bug report?
The console error, if one was thrown. An exact error message and stack trace tells a coding agent or human developer which file and line to investigate, which is the starting point for any fix. If there is no console error, the failed network call (method, URL, status code) is the next most important piece.
How long should a bug report be?
Short enough to read in under a minute, but complete enough to reproduce the bug without follow-up. A one-sentence description is usually too short; a three-paragraph narrative with guessed root causes is usually too long. Aim for: what you did, what you expected, what happened, and the evidence (console, network, URL).
Why does my coding agent keep saying "cannot reproduce"?
Usually because the report is missing the evidence the agent needs to set up the exact failure conditions. The most common missing pieces are the console error, the page URL, and the failed network call. If the agent is working from a prose description alone, it has to guess these, and it guesses wrong. A structured bug report template helps, but automatic capture at submit time is the reliable solution.
Does my bug report need steps to reproduce?
Yes, for most bugs. Numbered steps starting from a known state and ending at the failure let a coding agent replay what happened. Without them, the agent does not know whether the bug appears immediately or only after a specific sequence of actions. The steps to reproduce generator formats these correctly.
Can I use a template for all bug reports?
A template helps, but the fields that matter most (console error, failed network call) cannot be reliably filled in by users without tooling. A template with those fields empty is a form with blanks. It tells the filer what to include but cannot supply the data. Automatic capture via a widget fills the evidence fields before the user writes anything, so the template becomes a full report rather than a partial one. The Quell widget does this automatically.