Bug Report Template: Free Format for Developers & QA

A good bug report template is a fixed set of fields that forces the reporter to include the exact element, the steps to reproduce, and the expected versus actual result, so a developer or an AI agent can act without asking a single follow-up question. The format below is free, copy-paste ready, and built so the field reports usually skip, the precise UI element, is the one that gets filled in first.

Most templates you find online are long and get half-filled, which is worse than short and complete. The problem is rarely the reporter's effort; it is that the hardest field to write in prose is the one that matters most, and every template asks you to describe it in words.

What makes a bug report template that developers accept?

A format developers accept is one where every field removes a question the developer would otherwise have to ask you. If a field does not save a round-trip, it is padding, and padding is why long templates get abandoned.

The three fields that actually decide whether a report is actionable are the target, the repro, and the delta. The target is which element is wrong.

The repro is the exact steps to get there. The delta is what you expected versus what happened.

Everything else, severity, environment, a screenshot, is useful metadata, but a report with those three fields complete can be worked immediately. A report missing any one of them starts a conversation instead of a fix.

There is a worked bug report example that shows the difference on a real screen.

The reason short beats long is completion rate, not laziness. A twelve-field form asks for browser version and viewport size on every ticket, most of which do not need them, so reporters start skipping fields, and the skipped one is often the target.

A template that asks only for what makes the bug actionable gets filled to the bottom every time, which is the whole point of having a template.

The copy-paste bug report template

Here is the format. Paste it into your tracker, your bug report form, or your issue body and fill the fields top to bottom.

Title: [one line, what is broken and where]

Element: [the exact control , label, role, and where it sits]
URL / screen: [the page or window]
Environment: [OS, app version, browser if relevant]

Steps to reproduce:
1. 2.

3.

Expected: [what should happen]
Actual: [what happens instead]

Severity: [blocker / major / minor / cosmetic]
Evidence: [screenshot or recording, cropped to the element]

That is deliberately short. A tighter format of bug report beats a long one because it gets finished, and a finished report is the only kind that helps.

The one field worth obsessing over is Element. Write it so a developer who has never seen the screen can find the control on the first try.

"Primary Save button in the top toolbar, next to Cancel" beats "the save button" every time.

Why do bug reports get bounced back?

They get bounced because the developer cannot tell which element you mean, or cannot reproduce the steps, and has to come back to ask. Every bounce is a field the template should have forced but did not.

The most common bounce is the ambiguous target. On a busy screen, prose like "the dropdown near the top" maps to several controls, so the developer picks one, fixes it, and closes the ticket.

If they picked the wrong one, you reopen it, and the loop that a good template was supposed to prevent runs anyway.

The second most common bounce is the missing repro path. A bug that only appears after three specific actions is invisible if the report lists one.

Numbered steps exist to make the invisible path explicit.

The pattern in the right column is specificity per field. A report is only as fast as its vaguest field, so the template's whole job is to make the vaguest field impossible to leave vague.

How do you capture the element name and steps fast?

You capture the element by pointing at it instead of describing it, which is the one part of the template that prose makes slow. On a Mac, a point-and-speak capture tool resolves the exact control under your pointer and writes the Element field for you.

You hold ⌥⌘A, circle or point at the broken control, and speak the bug. The tool screenshots the region, transcribes your words on-device, and resolves the named accessibility element you circled, its role, label, and frame, with a confidence score.

The Element field stops being a sentence you agonize over and becomes a resolved fact.

This matters because the accessibility layer names things your eyes cannot. Two buttons that both read "Save" have different labels and positions in the accessibility tree, and the resolver reports which one you actually circled.

The mechanics of how that resolution works are covered in how AI agents know which UI element you mean.

The steps and delta still come from you, because only you know the path you took and what you expected. What the tool removes is the slowest, most error-prone field, so the rest of the template gets filled while the bug is fresh.

Speaking the report also captures nuance that a form field flattens. You can say "this only happens the second time you open the panel, not the first," and that timing detail lands in the report as you noticed it, rather than getting lost while you tab between fields.

The template gives the report structure; the voice capture keeps it honest to what you actually saw.

Can the same template feed an AI agent?

Yes, and that is the reason to name the element precisely even when a human is reading the report. The same fields that let a developer act on the first try are the fields an AI coding agent needs to act without guessing.

When the Element field holds a resolved accessibility element rather than a prose description, an agent can locate the matching component in the codebase by name instead of squinting at a screenshot. A capture can be filed straight to Linear, GitHub, or Slack, or handed to your agent over a local MCP server, using the same structured payload.

The routing options are laid out in point-and-speak bug reports to Linear and GitHub.

The whole point of a template is repeatability. A format that works for both a human and an agent is one you only have to learn once, and it is what turns filing a bug from a chore into a reflex.

The capture side runs on-device, with transcription and OCR through Apple frameworks and nothing uploaded by default. It ships as a notarized Developer-ID DMG and is a one-time $39 launch license through Polar rather than a subscription, and the pricing has the full detail if you want the capture step that fills the Element field automatically.

FAQ

#

What should a bug report template include?

At minimum the exact element, the steps to reproduce, and the expected versus actual result. Severity, environment, and a cropped screenshot are useful metadata, but those three fields are what make a report actionable without a follow-up.

#

What is the best format of a bug report?

Short enough to get finished, with the target named precisely. A one-line title, an explicit Element field, numbered repro steps, and separate Expected and Actual lines beat a long form that gets half-completed.

#

Why do my bug reports keep getting rejected?

Usually because the target is ambiguous or the repro path is incomplete. If the developer cannot tell which control you mean or cannot reproduce the issue, they bounce it back, so name the exact element and list every step.

#

How do I write the element field so a developer can find it?

Give the label, the role, and where it sits, for example "Save button, top toolbar, next to Cancel." On a Mac, a point-and-speak tool can fill this field with the resolved accessibility element so you do not have to describe it in prose.

#

Can I use one bug report template for both people and AI agents?

Yes, if the Element field holds a named target rather than only a screenshot. The same structured fields that let a developer act on first read are what an AI coding agent needs to locate the right component without guessing.

#

Should a bug report include a screenshot?

Include one cropped to the element as evidence for visual details like spacing or color. A full-screen image is weak on its own because it still does not name which control is wrong, so pair it with a precise Element field.