A bug report template developers will actually use

September 2, 2026 · 6 min read · by the Tracebird team

Most bug report templates fail for one reason: they ask the reporter for information the computer already has. Here is a template built on the opposite idea, and the five questions that actually need a human.

Why testers ignore your template

Ask a beta tester for their browser version, the exact URL, the steps to reproduce and the console output, and one of two things happens. Either they skip the form and message you “it doesn't work” on WhatsApp, or they fill it in wrong. Not because they are lazy: because you are asking a person to do a machine's job, in the moment they are most annoyed with your product.

A usable template separates the two halves. Humans are the only source of intent: what they were trying to do and what they expected. Machines are the better source of everything else: environment, logs, network, and what happened on screen.

The five questions only a human can answer

What happened. One sentence of observation. “The pay button spins forever” beats three paragraphs of theory about your payment provider.
What they expected. This is where half the “bugs” reveal themselves as design problems, which are worth knowing about too.
Where. A URL or a screen name. Enough to know which part of the product to open.
How bad. Blocked, annoyed, or cosmetic. Three checkboxes, because severity from the reporter's side is a feeling, not a P-level.
What they were trying to do. The task. Reproduction starts from intent, not from clicks.

The template

Paste this into your issue tracker, your form, or the pinned message of your testers channel:

bug-report-template.md

## What happened
One sentence. What you saw, not what you think the cause is.

## What you expected instead
One sentence.

## Where
Page or screen you were on. Paste the URL if there is one.

## How bad is it
- [ ] I'm blocked, I can't continue
- [ ] Annoying, but I found a way around it
- [ ] Cosmetic

## What you were trying to do
The task, in your own words. "Pay for my order", not "clicked the button".

---
Everything below this line should come from a tool, not from you:
app version, OS and browser, console errors, failed network requests,
steps to reproduce.

The half that should never be typed

Steps to reproduce, app version, OS, browser, console errors, the failing request: every one of these can be captured automatically at the moment the tester hits the bug. That is the actual fix for bad bug reports. A tool that snapshots the screen, the console and network activity and replays the test session behind the bug turns the template above from a chore into two sentences and a checkbox.

However you collect reports, hold the line on the split: never ask a human for what a machine knows, and never let a machine guess at what only the human knows.