Bug Reports for Agents: The Goal Is Not Clarity, It Is Fixed in One Pass

The conclusion first: a bug report for an agent aims not at "describing clearly" but at "fixed in one pass"

A bug report written for a human aims to make the human understand the problem. A bug report written for an agent aims to let the agent fix the problem in one pass — without rework, without breaking something new. Those goals sound close, but the methods are completely different. A human who reads "login sometimes fails" will ask follow-up questions, reproduce it themselves, and fill in missing information in their head. An agent that reads the same sentence will act directly on its own guess — if the guess is right, that is luck; if wrong, it is a round of rework plus a piece of previously fine code now broken.

So this guide's core claim is: a bug report must graduate from "problem description" to "fix specification." A report good enough to act on should tell the agent, before it touches anything: what the problem is, where it reproduces, what the expected behavior is, which places must absolutely not change, and how to prove the fix worked. Miss any one of these, and the agent works from guesswork — and guesswork is the source of rework.

Boundary: what this guide is not

Draw the boundary first, so you do not pick up the wrong document. This guide covers "a specific bug has been found — how do you write a report that gets it fixed in one pass?" The object is one bug, the action is writing the report, the endpoint is a verified fix. It is not a task acceptance checklist: an acceptance checklist governs a task's full journey from start to delivery (requirements, implementation, tests, documentation, release all complete). This guide governs only one link in that journey — the input quality of the "fix a bug" step. An acceptance checklist can tell you whether the bug-fix task counts as done, but it will not tell you which items a report needs for an agent to fix it first time.

Nor is it a user feedback triage guide: triage governs what happens after a pile of user feedback arrives — how to classify it, prioritize it, and assign it. That is traffic management for feedback. This guide governs what happens after triage, before hands touch code — how a single bug's report is written. That is writing for a single bug. The two are a relay, not substitutes: triage done well with a vague report still ends in rework; a report written well but triaged to the wrong person still goes down the wrong path. Nor is it a postmortem guide: a postmortem asks "why did this bug happen, and how do we improve the process?" This guide asks "how do we fix this bug now?" The time direction is different; do not mix them up.

The six mandatory parts of a report: none may be missing

First, the title: one sentence stating who, doing what, encountered what. A bad example: "Login has problems." A good example: "A signed-in user clicks Save on the settings page, sees an error, and the change is not saved." The test for a title: can someone with no background guess roughly where the bug lives from the title alone? If not, the title fails. A title is not a summary; it is the first clue for locating the bug.

Second, reproduction steps: in order, from "normal state" to "bug appears," including preconditions. The key is to write the minimal reproduction: if removing a step makes the bug disappear, that step is critical and should be marked; if a step makes no difference, delete it. Steps must include concrete input values — not "enter an email" but "enter test@example.com, leave the password blank, click Login." A bug an agent cannot reproduce will almost certainly be fixed wrong, because the agent does not even know what the problem looks like.

Third, actual versus expected results, side by side, as concretely as possible. Actual results should state "what was seen": paste the error message verbatim, describe the page state, write down the status code. Expected results should state "what should be seen": not "should work normally" but "should show a 'Saved' message, and after refresh the change should still be there." The more concrete the expected result, the clearer the agent's fix target; an expected result written as "should work normally" is the same as writing nothing.

Fourth, environment and versions: operating system, browser or app version, backend version, data state (new account or old account, any special data). Many "reproduces on my machine but not yours" bugs trace back to environment differences left unwritten. The rule for writing environment details: write until "a different person on a different machine can reproduce it from this report." Until that bar is met, the environment section is unfinished.

Fifth, impact and urgency: how many users are affected, whether the main flow is blocked, whether a workaround exists. This determines the agent's fix strategy: for a main-flow-blocking bug, the fix should prioritize "restore service first," and a temporary solution is acceptable; for a non-blocking edge bug, the fix should prioritize "introduce no regressions," slower and steadier. Without impact, the agent cannot judge whether to use a "fast and rough" or "slow and steady" strategy.

Sixth, places that must absolutely not change: the easiest item to omit, and the most important. State explicitly "do not modify module X, do not change the response format of interface Y, do not refactor part Z to fix this." An agent has no business context: it does not know which code looks awkward but must never be touched as historical legacy, nor which interface's response format an external system depends on. Omit this item and you implicitly permit the agent to refactor half the system to fix a small bug — and the new problems from that refactor are usually harder to trace than the original bug.

How to give evidence: logs, screenshots, recordings, each used correctly

Evidence is not better in larger quantities; it is better the more precisely it locates the problem. For logs, give the complete error stack, not just the last line — the last line is often just "some exception," while the real cause sits in a frame in the middle of the stack. Annotate logs with timestamps and the triggering action, so the agent can match log lines to reproduction steps; a pile of logs without timestamps forces the agent to guess which lines relate to this bug.

Screenshots are valuable for "page state": the full page at error time, console errors, network response bodies. Do not screenshot only the error popup — capture the address bar and page context too, because the popup itself usually carries the least information and the context carries the locating clues. Recordings are valuable for "operation sequences": when a bug depends on a sequence of operations, or only appears at a particular operating rhythm, a recording beats written steps. Record slowly, leaving pauses at each step, so the viewer can follow.

One class of evidence is often neglected: comparison evidence. If the feature used to work, find out "since when has it been broken" — the last time it worked normally, the most recent related code change, the most recent release. Such evidence can shrink the search from "the whole system" to "one change," which is enormously valuable to an agent. If you know these details, write them; if you do not, write "last normal time unknown" so the agent knows this clue is missing rather than assuming it does not exist.

How to write "expected behavior": from "should work" to verifiable assertions

Expected behavior is the easiest part of a report to write vaguely, and the most common source of rework. Three concrete methods turn "should work normally" into verifiable assertions. First, write concrete outputs: not "should save successfully" but "after clicking Save the page shows 'Saved,' after refresh the change is still there, and the corresponding database field has been updated." Second, write boundary cases: beyond the normal case, what should happen for empty values, overlong inputs, special characters, concurrent operations? If you are unsure about a boundary case's expected behavior, mark it "boundary behavior to be confirmed" rather than letting the agent guess. Third, write "how to verify after fixing": list verification steps, such as "walk the reproduction steps again and confirm the error is gone; run test suite X and confirm all pass; check log Y and confirm no new errors."

Verification steps serve another purpose: they give the agent a definition of done. Without one, the agent can only judge by feel whether the fix worked — if it feels right, it submits a possibly unfixed version; if it feels wrong, it keeps changing things and may break what was fine. With verification steps, the agent can run verification after each round of changes and stop when verification passes; the rework loop gains an exit.

One common trap to avoid: do not write your guessed cause into the expected behavior. For example, do not write "this is probably a database connection pool problem; fix the connection pool." Guessing causes is the agent's job, not the report's job; the report's job is to state the phenomenon and the expectation clearly and let the agent locate the cause itself. Writing a guess as a conclusion only steers the agent in the wrong direction — and once the guess is wrong, the agent may not dare question it precisely because "the report said so." Phenomena belong to the report; causes belong to the investigation. That division of labor must not be scrambled.

Five anti-patterns: ways of writing that guarantee rework

First, emotion instead of information: "This feature is completely unusable," "This is terrible." Emotion cannot locate a problem or guide a fix; in a report it is only noise consuming the agent's reading attention. Second, multiple bugs in one report: "Login has problems, and the profile page loads slowly, and search is a bit odd too." One report covers one bug; three bugs are three reports. Mixed together, the result is that the agent fixes one, misses two, or fixes none thoroughly. Third, conclusions without process: "Saving failed." Without reproduction steps, the agent can only guess at reproduction, and a wrong guess means a wrong fix.

Fourth, assuming the agent knows the background: "It's that same old problem again." The agent has no memory of yours; it does not know which old problem you mean, how it was fixed last time, or why it recurred. Background information must be written into the report; it cannot rely on "you should know." Fifth, listing several possible causes and letting the agent choose: "It could be A, or B, or maybe C." That is not rigor; it is abdication. The report's responsibility is to pin the phenomenon down; the investigation's responsibility is the agent's. Listing guesses only makes the agent try each direction halfway, and none of them thoroughly.

Checking your report against these five anti-patterns is the most worthwhile two minutes before writing it. Much rework is not an agent capability problem; it is the report pushing the agent in the wrong direction at step one.

Writing for different roles: users, testers, and developers each write differently

The same template filled in by different roles emphasizes different things, and saying so in advance saves many rounds of follow-up questions. When users or support staff write a report, the emphasis is "phenomenon" and "reproduction": what you did, what you saw, whether it reproduces reliably. No cause-guessing and no technical speculation are needed; one error screenshot plus three reproduction steps beats a page of technical analysis. When testers write a report, the emphasis is "coverage": beyond the main path, do boundary values, unusual inputs, and different environments reproduce it? Is there a known-good version to compare against? A tester's report is valuable for narrowing the search for developers and agents, not merely for proving "there is indeed a problem."

When developers write a report themselves (for example, handing a bug to an agent or a colleague), the emphasis is "constraints" and "evidence": how far the investigation has gone, which possibilities have been ruled out, which modules must absolutely not change, and the relevant code locations and recent change records. The most common mistake developers make is writing something that reads like technical notes — pages of investigation process with no clear statement of expected behavior and verification criteria. Remember: the report's reader is "the person who will fix it," not "the person who wants to understand your investigation." The process can be attached afterward as reference, but the front must first contain phenomenon, reproduction, expectation, and constraints. A team can preset different required fields by role in its bug template: users must fill phenomenon and reproduction, testers must fill coverage and comparison versions, developers must fill constraints and evidence. One template, three required-field combinations, and report quality rises a level immediately.

One cross-role rule applies to everyone: after writing, read the report through the "stranger test" — assume the reader knows nothing about this project and never worked on this feature. From this report alone, can they reproduce it and judge whether it is fixed? If not, whatever is missing is what you need to add. Many reports fail not from lack of care but from assuming the reader knows the background; the stranger test exists to break that assumption. Two minutes on this test after each report, and the rework rate drops visibly.

A template you can use directly

Title: [who] [doing what] [encountered what]. Reproduction steps: preconditions, steps in order, minimal-reproduction marking. Actual result: error message verbatim, page state, status code. Expected result: concrete outputs, boundary cases, verification steps. Environment: system, versions, data state. Impact: affected user count, main-flow blocked or not, workaround availability. Absolutely do not touch: a list of modules, interfaces, and response formats. Evidence: log stacks, screenshots, recordings, last-known-good time. And timelines: first occurrence time, most recent reproduction time, and last-known-good time — "worked last week, broken this week" alone narrows the investigation to the past week's changes rather than the whole system. Save this template and fill it in each time; for any item you cannot fill, write "unknown" rather than leaving it blank — "unknown" is itself information, telling the agent this clue needs finding rather than assuming it does not exist.

One final point: writing a bug report is not paperwork; it is half the fix. A good report gets a fix done in one pass; a bad report wastes three passes. Time spent writing the report is always cheaper than time spent on rework — because rework costs not only the agent's time but broken code, delayed releases, and eroded trust. Write the report well first, then let the agent act. That order cannot be reversed.