The fastest bug to fix is the one a developer can reproduce on the first try. Most of the time lost on bugs isn’t spent fixing them; it goes on the back-and-forth before anyone understands what actually happened.
After ten years of writing bug reports for banks, insurers and product teams, I use the same structure every time. It answers five questions before anyone has to ask them.
1. A title that says what broke and where
The title is what people scan in a list of fifty tickets. Make it specific: where it happens, what happens, and the condition that triggers it.
- Weak: “Checkout broken”
- Better: “Checkout: order placed twice after double-tapping ‘Pay now’ on iPhone”
Someone who reads only the title should already know which part of the product to open.
2. The environment
Where were you when it happened? Many bugs only exist in one browser, on one device or in one build. Write down:
- URL or environment (staging, production) and build or version number
- Browser and version, device and operating system
- The user or role you were logged in as, if it matters
3. Steps to reproduce
Numbered, short, one action per step. Start from a state anyone can reach, such as “logged out, empty cart”. Include the data you used, because “a long name” and “Zoë O’Brien-Ramírez” are not the same test.
Then reproduce it yourself once more by following only your own steps. If you can’t, the report isn’t ready yet.
4. Expected and actual result
Two short sentences, side by side. Expected is what should have happened, according to the requirement, the design or common sense. Actual is what did happen.
This is where many reports go vague. “It doesn’t work” is an actual result nobody can act on. “Two orders are created and the confirmation email arrives twice” is one a developer can start on straight away.
5. Evidence and priority
A screenshot shows the result; a short screen recording shows how you got there. For anything involving timing, like double clicks or slow loading, a recording is worth ten screenshots. If you can, add the error from the browser console or the failing request from the network tab.
Finally, set the priority by user impact: can people still complete the journey? Is money or data involved? How many users will hit it? Leave out the adjectives. “Blocks guest checkout on iOS” carries more weight than “very urgent!!!”.
A template you can copy
Title: [Area]: [what happens] when/after [condition]
Environment: [URL / build] · [browser + version] · [device + OS] · [user role]
Steps to reproduce:
1.
2.
3.
Expected result:
Actual result:
Frequency: [e.g. 3/3]
Evidence: [screenshot / recording / console error]
Priority: [Critical / High / Medium / Low], because [user impact]
Notes: [what you also tried, where it does NOT happen]The last line matters more than it looks. “Not reproduced on desktop Chrome” is a clue that often points the developer straight at the cause.
One bug, one report
It’s tempting to list three small issues in one ticket. Don’t. Separate reports can be prioritised, assigned and closed independently. Combined reports tend to stay half-open for weeks.
A good bug report is a small act of respect for the person who has to fix it. Write the one you’d want to receive.
Frequently asked questions.
What is the most important part of a bug report?
The steps to reproduce. If a developer can make the bug happen on their own machine, they can usually fix it quickly. Everything else in the report helps them get there faster.
Should one bug report contain several bugs?
No. One report per bug. Separate reports can be prioritised, assigned and closed independently; a combined report tends to stay half-open for weeks.
What is the difference between severity and priority?
Severity describes how bad the effect is for the user. Priority describes how soon the team should fix it. A typo on the homepage has low severity but can still have high priority before a launch.
