Writing a Bug Report People Can Act On

A bug report is a request for someone else's time. If the reader has to guess what you saw, what you expected, or how to reproduce it, the ticket sits untouched for a week. A good report is short, specific, and testable. This template gives you the five lines that matter, plus the wording that keeps a report factual instead of dramatic. Write it once, and the fix usually starts the same day.

"Title: Checkout fails with a 500 error when the cart holds more than ten items. Summary: On production, adding an eleventh item and pressing Pay returns a 500. No order is created and the user lands on a blank page. First seen on 21 July at 14:20, still reproducible this morning. Roughly one in twenty checkouts. Chrome 140, macOS, logged-in accounts only."

Two things make this title useful. It names the symptom and the trigger in one line, so anyone scanning a hundred tickets knows in a second whether it is theirs. The summary then answers the three questions a triage engineer asks: what broke, how often, and where. Note the missing word — nowhere does it claim that checkout is completely broken. Exaggeration costs you credibility the first time someone checks.

"Steps to reproduce: 1. Log in as a standard user. 2. Add eleven items to the cart. 3. Press Pay. Expected: the order is created and the confirmation page loads. Actual: the page goes blank and the server logs a 500. Not seen with ten items or fewer, and not seen for guest checkout. Attached: a screen recording, the request ID, and the relevant log lines."

This is the part people skip and the part engineers need most. Numbered steps let a stranger reproduce the bug without asking you a single question. Expected and actual, side by side, remove all argument about whether it is a bug at all. And the attachments do the work for you: a request ID turns a vague story into a line an engineer can look up in seconds.

"Impact: about fifty carts a day hit this, and those users cannot pay at all. Support has had six tickets since Monday. Ask: could someone take a look today? I am happy to be the tester once there is a build. If this is already known and tracked elsewhere, point me at that ticket and I will close this one as a duplicate."

Impact is what moves a ticket up the queue, so give a number rather than an adjective. Fifty carts a day is something a lead can decide on; critical is an opinion. The ask is equally concrete: a clear request, an offer to help, and an easy exit if this turns out to be a duplicate. That last line makes you the kind of reporter people are glad to hear from again.

One last habit. Report what you observed, not what you think the cause is. "The cache is broken" sends someone down your theory; "the price shown is stale after an update" sends them to the evidence. If you do have a theory, put it at the bottom and label it a guess. Keeping observation and speculation apart is the difference between a report that helps and one that misleads.