Writing a Bug Report That Engineers Will Act On
Supply the details engineers need to investigate without asking follow-up questions.
A bug report earns action by supplying the information an engineer needs to investigate without first interviewing the reporter. Writing one well means closing predictable gaps in the title, reproduction steps, environment, and evidence. A report should make the failure reproducible, the impact clear, and the eventual fix verifiable.
Why most bug reports get ignored before an engineer reads past the title
Each missing detail leads to a question, and each back-and-forth gives the ticket another chance to lose priority. “The checkout is broken” arrives in Slack, but checkout works for the developer. The browser and account emerge only after separate questions, and eventually someone schedules a call to demonstrate the failure. It takes three days to understand a bug that takes ten minutes to fix.
This is not evidence of laziness or bad intent. The reporter witnessed the problem but did not preserve enough of that experience for someone else to reconstruct it. Vague titles hide scope, missing evidence blocks investigation, and inflated severity obscures real urgency. The remedy is a field-by-field anatomy of an actionable report, with a distinct job assigned to each field.
Writing a title that does triage work before anyone opens the ticket
The title helps an engineer tell whether the ticket matters to their work before opening it. “Login doesn't work” and “Payment bug” identify broad areas but omit the failure and its conditions. By contrast, “Checkout button does nothing on mobile Safari” names the component, observed behavior, and affected environment. It does the work that “checkout broken” leaves to the reader. The useful pattern is a component, what breaks, and the trigger condition.
A title should also expose impact when that impact is known. “Blocks all purchases on iOS” signals a different response from “typo in footer” without relying on an urgent label. Specificity carries more information than emphasis because it tells the triage engineer what is at stake. Before filing, search the tracker by component or keyword, since fresh reproduction data may be more useful on an existing ticket than in a duplicate.
Reproduction steps: writing them so a stranger can trigger the same failure
Once the title names the failure, reproduction steps give another person a way to trigger it. This is the most important field because an engineer who cannot reproduce the problem must seek clarification or return “cannot reproduce.” Start from a known state, such as “logged in as admin user.” Put the account type, role, feature flag, and locale together in the preconditions. These conditions define the starting point.
Write the steps as numbered, discrete actions, with preconditions as step zero. In the profile example, the sequence begins by navigating to /profile. The next action is clicking “Edit Profile,” followed by changing the email field to test@example.com. The final action is clicking “Save Changes,” after which an error appears where a success confirmation is expected. Specific control names, field values, and expected wait times keep the reader from having to guess what the reporter did.
State that the bug is intermittent, estimate its frequency, and record any preconditions or data shapes that appear to correlate with it. “Sometimes it breaks” supplies no useful boundary for investigation. A rough frequency and details about the account give the engineer something to reproduce even when the failure does not happen every time.
Expected versus actual results: turning an observation into a testable claim
Reproduction establishes how to reach the failure, but expected and actual results establish what makes it a failure. Keep the contrast to two short lines, one for the expected outcome and one for what happened instead. For checkout, the expected result is an order confirmation page. The button spinner runs forever, with no navigation. The fix becomes verifiable when actual behavior matches the stated expectation.
The expected result must therefore be specific enough to serve as an acceptance criterion. “It should work” cannot do that job. “The page shows a 500 error” records an observation, while “the server is broken” introduces an unproven explanation. Put any root-cause hypothesis in a separate, clearly labeled note after the evidence.
Environment details: the information that explains "works on my machine"
Even exact steps can fail to reproduce a bug when the engineer runs them in a different environment. The environment field closes that gap by recording where the observation holds. For a web bug, include the browser name and exact version, operating system and version, device model where relevant, and exact page URL. Record the viewport size, account type or role, and whether the failure occurred on local, staging, or production. A broad label such as the browser name alone leaves an important variable unresolved.
Mobile reports also need the app build number from the about page, locale, user role, and active feature flags, together with the OS version and device model. The failure may depend on one particular combination of those variables. Where known, include the app version or commit hash to pin the report to a code state. That matters when a failure appears after a release or when several deployments separate the observation from the investigation. An account detail that feels obvious to the reporter may be the condition that explains the entire discrepancy.
Console errors, network evidence, and why screenshots of text do not substitute for the text itself
A developer cannot copy, search, or grep a screenshot of an error. Console output belongs in the report as text because exact error strings, codes, and stack traces can be matched against the codebase. Copy the full error rather than paraphrasing it, and paste it into a code block. Report the console’s observations. Images are useful for visual evidence, but they are not a substitute for searchable text.
For failures involving loading, saving, submitting, or authentication, include network evidence as well. Write down the URL of the failing request, its HTTP method and status code, and the response body if it is visible. These fields preserve the request and response behind “saving failed. Console and network evidence answer different questions, so one does not automatically replace the other. Together they give the engineer a more precise starting point than the visible symptom alone.
A screenshot or short recording still has a distinct role. It can show a layout problem, a timing-dependent failure, or something that flashed and disappeared. A recording also removes ambiguity when people use different names for the same page or control. It supplements the written steps and machine-readable evidence.
Severity and priority: two distinct calls that often get collapsed into one
Severity measures technical impact, while priority measures business urgency relative to other work. Critical severity is for bugs that block core functionality, prevent authentication, or cause data loss. High describes a major broken feature with a workaround, while Medium covers partial failures or a subset of users. Low covers cosmetic issues that do not affect the core user experience or revenue. Teams should spell out these thresholds because a bug's impact depends on the product, who uses it, and how it makes money.
Priority answers when the fix needs to happen. P2/Major means the next release cycle, while P3/Minor means when capacity allows. A bug that affects paid or enterprise customers can call for escalation even when its technical severity is lower. Support either judgment with a short impact statement naming who is affected and whether a workaround exists. Marking every issue Critical erodes trust in the field and makes genuine blockers harder to distinguish.
How AI coding agents change what a well-formed bug report requires
A human can draw on context or ask a follow-up question, while an agent may fill the gap with a plausible assumption. That assumption can lead to a fix made with confidence that is wrong but passes the first review. Write as though the first reader is a machine and the second is a human.
Exact error strings and full stack traces let the agent match the evidence to the code. Request and response pairs with status codes help find the failing endpoint, while exact URLs link what happened to routes and components. In a multi-repository environment, the service or repository name identifies which codebase to inspect. Structured fields make these details explicit instead of leaving an agent to extract them from a narrative. Each field narrows the room for unsupported inference.
A complete ticket still cannot carry all the context needed for every fix. A change to a field may seem local but affect several services, teams, or languages. An agent looking into such a change may need cross-repository context beyond what the report can give it. Structured access to organization-wide code intelligence, including through connected tool interfaces, gives the agent that missing context. The report scopes the investigation, but it does not replace knowledge of the surrounding system.
The failure modes that persist even when reporters know the rules
Knowing the rules does not mean applying them consistently under time pressure. Reporters still substitute a diagnosis for an observation, file from memory after the code has changed, or capture text as an image because it is quicker. They also omit account conditions that seem too obvious to mention. These are recurring capture failures rather than gaps that another explanation of good writing will necessarily resolve. The way reports are filed must make it hard to miss the evidence they need.
Use a shared template with required fields and capture information at the moment of failure. A field that explicitly asks for pasted console text removes a decision that otherwise falls to the reporter. This matters when product staff, support staff, and new hires have to write reports without the habits of a QA professional. It matters more when the next investigator is an agent that cannot ask clarifying questions.
Keep one bug in each report because separate failures have separate lifecycles. Bundled tickets can be partly fixed and closed while unresolved issues disappear from tracking.
A complete bug report template, with notes on what each field is actually for
Use these field labels as the shared report structure. Remove a field only when it genuinely does not apply, retaining fields for which evidence has yet to be collected.
Title. [Component] + what breaks + trigger condition. Give the triage reader enough information to understand the issue before opening it.
Steps to reproduce. [Known starting state and preconditions, followed by numbered actions]. Put details about the account in step zero and, if the bug is intermittent, note that and how often it seems to happen.
Expected result. [Specific behavior that should occur]. This is the acceptance criterion for the fix.
Actual result. [Observed behavior and exact error text]. Describe the failure without inserting a diagnosis.
Environment. [URL, browser and exact version, OS and version, device, viewport, account and role, app version or commit, and local, staging, or production]. For a mobile bug, add the app build number, the locale, and the feature flags that are active.
Repository or service. [Affected repository or service name]. Require this field in multi-repository environments so an agent can scope its investigation.
Console output. [Full console errors and stack traces as pasted text in a code block]. Preserve the strings that a developer or agent can search.
Network evidence. [Failing request URL, HTTP method, status code, and visible response body or error message]. Include this for loading, saving, submitting, and authentication failures.
Attachments. [Screenshots or recording]. Use images for problems with how something looks and recordings for failures that depend on the sequence of actions or the state.
Severity. [Critical, High, Medium, or Low]. Describe the technical impact based on the thresholds the team has set.
Priority. [P1, P2, or P3]. State business urgency and note any paid or enterprise customer impact.
Impact. [Affected users, extent of disruption, and available workaround]. Keep the evidence supporting the triage decision to one or two lines.
Additional context. [Tickets about related issues, when the issue started, customer feedback about it, or stack traces not included above]. Place any root-cause hypothesis here and label it as a hypothesis.
