Most bug reports die in the backlog — not because the bugs aren't real, but because the reports don't give developers what they need to reproduce them. A developer who can't reproduce a bug can't fix it. And a bug they can't fix gets closed as "cannot reproduce" or deprioritized indefinitely.
Here's the format that changes that.
1. Write a title that describes the symptom, not the suspicion
Bad: "Checkout broken"
Good: "Clicking Place Order on the checkout page shows a spinner that never resolves — order is not created"
The title should let a developer understand what broke without opening the ticket. Avoid vague words like "broken," "weird," or "not working." Describe what the user sees.
2. List exact steps to reproduce
Number them. Make each step atomic — one action per line. Write them so that someone who has never used the product before could follow them and hit the same bug.
Example:
- Log in as a guest user (no account).
- Add any item to the cart.
- Navigate to
/checkout. - Fill in a valid shipping address and click Continue.
- Enter test card
4242 4242 4242 4242and click Place Order. - Observe: spinner appears and does not stop. Order page is never shown.
If you can't reproduce the bug yourself on demand, say so — and describe the conditions under which you did see it. That's still useful information.
3. State expected vs. actual behavior
Two short paragraphs, clearly labeled:
Expected: After clicking Place Order, the user is redirected to an order confirmation page and receives a confirmation email.
Actual: A loading spinner appears on the button. The page does not change. No confirmation email is sent. The spinner continues indefinitely.
This matters because "expected" isn't always obvious. Developers need to know what correct behavior looks like before they can verify they've fixed the right thing.
4. Include environment details
Bugs are often environment-specific. Always include:
- Operating system and version (e.g., Windows 11, macOS 14.5)
- Browser and version (e.g., Chrome 124, Safari 17)
- App version or build number
- Account type or role (guest, free plan, admin)
- Any relevant feature flags or settings
If you tested on multiple environments, say which ones showed the bug and which didn't. "Reproducible on Chrome/Windows, not on Safari/macOS" is a huge clue.
5. Attach a screen recording
A screen recording is worth a hundred words of description. It shows the exact sequence of actions, the exact UI state, and what happened — without any interpretation errors.
Screenshots are fine for static UI bugs. For anything with a sequence of steps, timing, or intermediate states, use a recording. Keep it short — under 90 seconds — and start it a few seconds before you trigger the bug so the developer can see the lead-up state.
If you can, annotate the recording to highlight what to look at. Drawings, arrows, and timestamps let the developer jump to the moment that matters without scrubbing through the whole video.
6. One bug per report
A report that covers three issues gets partially fixed, or not at all. When bugs are bundled, no one knows whether "fixed" means all three or just one. Split them. Each bug gets its own ticket, its own priority, and its own owner.
The final check
Before you file the report, ask yourself: could a developer reproduce this bug without sending me a single follow-up question?
If the answer is yes, file it. If not, you're missing something — go back and add it. The ten minutes you spend writing a complete bug report saves hours of back-and-forth and gets the fix shipped faster.