Most bug reports fail the same way. Someone writes “the contact form is broken,” a developer spends twenty minutes failing to reproduce it, asks which browser, waits a day for the answer, and the fix that should have taken ten minutes has cost the better part of a week in calendar time.
None of that is a skill problem. It's a missing-fields problem. A bug report only has one job: give whoever picks it up enough to reproduce the bug on the first attempt. Below is the template, then the reasoning behind each field, then the part nobody solves — getting clients to actually use it.
The template
Paste this into your tracker, your issue template, or the top of whatever document your client reports into. It is deliberately short: every field earns its place by being something a developer would otherwise have to ask for.
## Title
[What is broken] on [where] when [under what condition]
## URL
The exact page the bug happens on (including any query string)
## Steps to reproduce
1. Start from ...
2. Click ...
3. Enter ...
4. Observe ...
## Expected result
What should have happened.
## Actual result
What happened instead, word for word if there was an error message.
## Severity
Blocker / Critical / Major / Minor / Cosmetic
## Environment
- Browser + version:
- Operating system:
- Device:
- Screen size:
- Logged in as:
## Evidence
Screenshot, screen recording, or console output.
## Notes
Anything already ruled out, and whether it reproduces every time
or only sometimes.Why each field is there
The fields are not arbitrary. Each one exists because leaving it out reliably costs a round trip.
A title that names the behaviour
“Checkout broken” tells a triager nothing. “Submit button does nothing on mobile checkout when the discount field is empty” can be routed, estimated, and often diagnosed from the title alone.
The URL, not the page name
Staging and production drift. Query strings change behaviour. “The pricing page” is ambiguous the moment a site has more than one of them.
Expected and actual, kept separate
Half of all reported bugs turn out to be misunderstandings of intended behaviour. Splitting the two fields surfaces that in the report instead of in a meeting.
Environment, in full
Browser, OS, device and viewport are the four variables behind most “works on my machine” standoffs. Screen size matters more than people expect on responsive builds.
Steps to reproduce are the whole report
If one field is going to be done badly, it will be this one. The usual failure is starting in the middle: “click submit and it fails” assumes the reader already got to the form, logged in as the right user, and filled it the same way.
Start from a state anyone can get to — a logged-out home page, a fresh incognito window — and number every action from there, including the data typed in. The test is simple: could someone who has never seen this bug follow your list and hit it on the first try? If not, the list is incomplete.
One more line worth adding: whether it happens every time. A bug that reproduces one time in five is a different investigation than one that reproduces always, and knowing which saves a developer from concluding it is fixed when it isn't.
Severity is not priority
These get conflated constantly, and the result is a backlog where everything is urgent. Severity is how badly the product is broken, and the reporter can judge it. Priority is when it gets fixed, and that depends on the release plan and the commercial context, so it belongs to whoever owns the roadmap.
| Severity | Means | Example |
|---|---|---|
| Blocker | Nobody can use the product, or a whole flow is dead | Site returns a 500 on every page |
| Critical | A core flow fails with no workaround | Checkout never completes payment |
| Major | A real feature is broken but has a workaround | Search returns nothing unless you sort first |
| Minor | Something is wrong but the flow still works | Validation message shows the wrong field name |
| Cosmetic | Visual only, no functional impact | Heading sits 4px off at one breakpoint |
Write the definitions down once and put them where people report, not in a process document nobody opens. A shared scale is what makes the word “critical” mean the same thing to a client as it does to your developer.
The client problem
Here is the uncomfortable part. This template works beautifully for your internal QA and almost never survives contact with a client.
Clients report bugs the moment they notice them, from whatever they happen to be holding, in whatever channel is already open — a reply to an email thread, a message in a chat, a phone call. Asking them to stop, find a form, open developer tools to read a console error, and identify their own browser version is asking them to do QA work they were never hired for. Most will send “the page looks weird on my phone” and a photo of a screen, taken with another phone.
The workable answer is not stricter process. It's to stop asking humans for the fields a machine already knows. Browser, OS, device, viewport, page URL and the state of the page at the moment of the report are all knowable automatically. What genuinely needs a person is the description of what looked wrong and where they were pointing.
That is the split tapko.app is built around: the client taps the spot on the page that looks wrong and types a sentence, and the environment fields, the URL and the annotated screenshot are captured with it. The report arrives already carrying the parts of this template a client would have skipped. If you want the wider picture on getting feedback out of email threads, this guide covers the workflow, and this comparison covers the tooling.
Adapting it to your tracker
Keep the template short enough that it gets filled in. If you use GitHub, this maps cleanly onto an issue template. If you use ClickUp, Jira, Linear or Trello, each field becomes either a custom field or a section in the description — custom fields are worth it for severity and environment, because those are the two you will want to filter and group by later.
Resist the urge to add fields. Every extra required field lowers the odds the report gets written at all, and a half-filled template is worse than a short one, because it looks complete while missing the thing you needed.
Where the template sits in the project matters too. Bug reports arrive in two very different moments — the internal QA pass before handover, and the client review round after it — and those want different handling. The pre-launch QA checklist covers the first, and the website project plan template covers where both of them fall in the timeline.
A bug report is not documentation. It is a handoff, and it succeeds or fails on one question: can the next person reproduce this without talking to you? Everything in the template above is there because it answers that question, and everything not in it was left out because it doesn't.
Frequently Asked Questions
What should a bug report template include?
A title that names the broken behaviour, the URL, steps to reproduce, expected versus actual result, severity, environment (browser, OS, device, screen size), and a screenshot or recording. Everything else is optional; without those fields a developer has to come back and ask.
How do you write steps to reproduce?
Start from a known state such as a logged-out home page, then number every action in the order you took it, including the data you typed. The test is whether someone who has never seen the bug can follow the list and hit it on the first try.
What is the difference between bug severity and priority?
Severity describes how badly the product is broken, which the reporter can judge. Priority describes when it gets fixed, which depends on release plans and commercial context and belongs to whoever owns the roadmap. Keeping them separate stops every report arriving marked urgent.
How do you get clients to fill in a bug report template?
Mostly you do not. Clients report bugs in the moment, by email or chat, and a form they have to find first gets skipped. The practical fix is to capture the technical fields automatically at the point of reporting so the client only has to describe what looked wrong.