Writing a bug report that gets fixed

Two people call a plumber about the same problem.

The first says: "There is water everywhere in the kitchen." The plumber asks four questions, cannot picture it, and offers a slot next Tuesday.

The second says: "The pipe under the kitchen sink drips, but only while the dishwasher is running. It started after we moved the dishwasher on Saturday. There is a bowl catching about a cup an hour." The plumber knows what to bring and comes today.

Same leak. A bug report template is just the second version, written down so you produce it every time.

The seven lines of a bug report

• Title. What breaks and when, in one line. "Partial gift-card redemption rounds the balance down by 1p" rather than "Gift card bug".
• Environment. Build or version, environment name, browser and version, account used.
• Steps. Numbered, starting from a state anybody can reach, with real data values.
• Actual result. What happened, quoted or shown, not summarised.
• Expected result. What should have happened, and where that expectation comes from.
• Evidence. Screenshot, video, network response, log excerpt, run id.
• How often. Every time, or two in five. This one line changes how the bug gets prioritised.

Why you should care about this

Because the report is the most visible thing you produce all week, and it is judged.

An engineer who reads a clear report spends their time on the fix. An engineer who reads a vague one spends it interviewing you, and after the third round of that your reports get read last. Nobody says this out loud, but everybody sorts their queue this way.

There is also a hard commercial edge. A bug that arrives with reproducible steps and evidence gets triaged on the facts. One that arrives as a paragraph of prose gets triaged on how confident the reporter sounded, which is not a system anybody should want.

How to write one that gets fixed

1. Reproduce it twice before you write. Once to see it, once to work out the shortest path. The second run is where you discover which step is actually required.
2. Start the steps from a known state. A named account, a seeded card, an empty basket. The same discipline as writing a test case a stranger can run.
3. Quote the actual result. The exact error text, the exact number on screen. "The total was wrong" tells the reader nothing they can search for.
4. Say where the expectation comes from. The acceptance criteria, the policy document, the design. Otherwise the discussion becomes your opinion against theirs.
5. Attach the smallest useful evidence. One screenshot with the number visible beats a four-minute video.
6. Note the frequency. Two in five attempts is a different bug from every time, and it points at data or timing.
7. File it against the case if you have one. A report joined to a case and a run answers "when did this last work" without archaeology. That is what a record a release rests on is for.

The same bug, both ways

For example, here is the report that goes nowhere and the one that gets fixed, for the same defect in the gift-card release at Willow Books.

The last two lines are worth copying as a habit. Naming the pattern (only totals ending in .49 or .99) and doing the arithmetic out loud turns a report into a lead. That is often the difference between a fix this afternoon and a fix next sprint.

How to show you know it

• A before-and-after pair like the one above, from your own tracker. It is the clearest demonstration of the skill that exists.
• A pattern in the frequency line. Spotting that it only happens on certain totals, browsers or accounts is the tester's contribution to the fix. Run history is where those patterns hide.
• A closed-as-cannot-reproduce report you rescued. Finding the missing state and reopening it with steps that work is a good interview story.
• Reports joined to cases and runs. It shows you think about the record and not only the ticket.