A bug report fails when the developer has to write back asking what browser you used, what you expected, or where exactly the broken thing lives. Every round trip costs a day. The template below cuts those questions off at the source. Copy it, paste it into your review tool of choice, and adjust the optional fields to match your stack.
Every field has a reason. The notes after the template explain when to keep a field, when to drop it, and what a good answer looks like.
The template
Use this as the body of a single bug item. One bug per item. If you find three bugs on the same screen, file three items, not one long one.
Title: [Screen or component] [verb] [unexpected result]
Severity: Blocker / High / Medium / Low
Environment: [URL or build], [browser + version], [OS], [device or viewport], [logged-in user role]
Preconditions: What state the system must be in before the steps work. Account type, feature flags, seeded data.
Steps to reproduce:
- First action, including the exact button or link text
- Second action
- Third action, ending at the moment the bug appears
Expected: One sentence on what should happen.
Actual: One sentence on what does happen, plus any error text copied verbatim.
Evidence: Screenshot with a pin on the broken element. Console error if relevant.
Frequency: Always / Intermittent (X of Y tries) / Once
Regression: Worked in [build or date], broke in [build or date]. Unknown if you cannot tell.
Workaround: What the user can do to get past it, or None.
What each field is for
Title. The title is read in a list of fifty other titles. "Checkout button does nothing on mobile Safari" beats "Bug in checkout" every time. Put the screen first so a developer scanning by area finds it fast. Skip words like "issue" and "problem" that add no information.
Severity. Keep four levels, not seven. Blocker stops a release. High breaks a core flow but has a workaround. Medium is a clear defect in a non-core path. Low is cosmetic. If your team already has a scale, use that and delete this row.
Environment. The single most common cause of "cannot reproduce" is a missing environment line. Always include the URL or build number, the browser with version, and the viewport if the bug is visual. For mobile, include the device model. For desktop, the OS version matters less, except for font and scrollbar bugs.
Preconditions. Drop this row when the bug appears on a public page with no login. Keep it when reproduction depends on account state, like "trial user with no payment method on file" or "admin with the new-billing flag enabled."
Steps to reproduce. Number them. Each step is one action. Use the exact button text in quotes so the developer searches the codebase and finds the component. Stop the steps at the moment the bug appears, not three actions later.
Expected and Actual. Keep these to one sentence each. If you need a paragraph, the bug is actually two bugs. For error messages, copy the text exactly, including punctuation and any code in parentheses. Screenshots of error toasts are good, but the typed text lets the developer grep for the string.
Evidence. A screenshot with a pin on the broken pixel is worth more than three paragraphs of description. For layout bugs, capture the full viewport so the developer sees what is around the broken element. For console errors, paste the stack trace as text, not as a screenshot.
Frequency. An intermittent bug is a different beast than a deterministic one. "3 of 10 tries" tells the developer to look for a race condition, not a logic error. If you only saw it once and cannot reproduce, say so. A one-time bug is still worth filing.
Regression and Workaround. Both are optional. Include Regression when you know a previous build worked, since it narrows the search to a diff. Include Workaround when one exists, since it lets the team decide whether to ship with the bug open.
How to attach the screenshot without slowing down
The friction in most bug reports is not the writing. It is getting a screenshot into the ticket with a clear marker on the broken element. If you use a desktop tool, you screenshot, save, drag into the ticket, then describe the location in words because nothing on the image points at it.
A browser-based capture tool removes that step. With Cobalt Capture for QA bug reports, you open a tab, click Capture screen, crop the still, drop a numbered pin on the broken element, and either type or dictate the fields above. There is no install and no signup. Publish gives you a short review link you paste into Jira, Linear, or Slack, plus a clean markdown version at /r/<slug>/markdown if a developer wants to pipe it into an editor.
If your team works with AI coding agents, the markdown export is what Cursor or Claude Code reads natively. The same review serves both audiences, which is the point of agent-readable feedback: humans get the pretty link, agents get the text.
When to trim the template
The template above is the long form. Use it for bugs going into the official tracker. For quick QA passes on a staging build, drop Preconditions, Regression, and Workaround, and keep the core seven fields. For a single-developer side project, you can go down to Title, Steps, Expected, Actual, and Screenshot.
The fields you should never drop are Steps, Actual, and Evidence. Without those three, the report is a wish, not a bug. If you find yourself filing the same kind of bug repeatedly, look at the mistakes that make screen feedback hard to act on before tuning the template further.
Make it the team default
Paste the template into your team wiki and link it from the QA channel topic. Pin it in the issue tracker as a saved template if your tracker supports them. The point is that everyone files bugs in the same shape, so developers stop guessing what each reporter means by "broken." Pair it with a staging site review pass before each release and the count of "cannot reproduce" tickets drops fast.
Start your next bug report at a fresh capture session and fill the fields as you go. The template stops being a checklist after a week of use; it becomes how you think about a bug.