How to Write a Bug Report: Format, Severity and Real Examples

Every bug report is a small piece of persuasion or discovery. The reader is a busy developer who owes you nothing and your report is competing with forty other reports, two meetings and a build that just broke somewhere else. A good report gets read because it respects that reality: it lets the developer reproduce the problem, understand it and decide what to do without ever asking you a follow up question. A bad report costs the team more time than the bug does.

The good news is that quality here is a formula and the formula is learnable in an afternoon. Let's take it apart.

What does a good bug report actually contain?

One defect, one report. That's the first rule, because bundles hide patterns: if the shop bug and the inventory bug share a root cause, separate reports let the team see how many systems it touches.

Beyond that, the anatomy is stable across almost every studio and tracker:

• A title that identifies the area and the problem
• Reproduction steps that start from a predictable state
• Expected behavior versus actual behavior
• Environment details (platform, build, settings that matter)
• Frequency, honestly estimated
• Attachments that prove rather than decorate

Miss one of these and the report comes back with questions. Include all of them and it usually just gets fixed.

What goes in the title?

A title should answer "where" and "what happened" in one line. Compare "Game broken!!!" with "Shop: gold balance desyncs after buying a weapon while a crafting queue completes." The second title lets a developer route the bug to the right person before even opening it. That routing is the real job of a title and vague titles slow entire teams down.

A useful pattern: [Area]: observed behavior under specific condition. Keep special characters out of it so search and filters behave and resist the urge to put severity or jokes in the title line. Both age badly.

How do you write reproduction steps?

Numbered steps, each one a single action, starting from a state anyone can reach. Specify exact inputs and menu paths, not vibes. "Fight some enemies" is not a step. "Defeat the two guards outside the east gate using ranged attacks" is.

Two habits separate professionals here. First, minimize: once a bug reproduces in five steps, spend ten minutes trying to make it three. Every step you remove is multiplied by every future reader. Second, if the bug is intermittent, say so honestly with an estimate: "reproduces about one time in five; seems more likely when the queue has at least two items." A known flaky repro with data is gold. An unknown flaky repro that silently fails for the developer is how reports die.

Why do expected and actual results matter?

Because "wrong" is not information. The developer needs to know which rule you believe the game broke, so they can agree or disagree with specifics. Expected behavior comes from the design if you know it, or from reasonable consistency if you don't: every other container in the game stacks to 99, so this one probably should too.

Keep the pair adjacent and explicit. "Expected: the gold total decreases by the item price. Actual: gold drops to 0 and the item doesn't appear in inventory." Two lines and suddenly the developer can picture the failure without opening the game.

What environment information belongs in the report?

Enough to reproduce and no more. Platform and OS version, build identifier, relevant hardware (GPU and CPU on PC, device model on mobile), language and any setting the bug depends on, like graphics presets or control schemes. If you're not sure whether a setting matters, mention the ones you changed recently. The reader can prune; they can't mind read.

Severity versus priority: what's the difference?

Severity describes damage to the product: a crash on launch is high severity, a typo in a tooltip is low. Priority describes urgency in the queue and the team sets it, because urgency is a product decision, not a measurement. They don't have to match.

A typo on the title screen is trivially easy to fix but blocks every trailer and first impression, so it can be high priority with low severity. A crash in a room players can only reach through an obscure side quest might be high severity sitting at low priority for weeks. Testers propose severity; they suggest priority politely and let the team own it. Marking everything "critical" is the fastest way to have your severities ignored, which hurts you on the day you find a real critical bug.

What does a bad report look like next to a good one?

Bad: "The shop is broken. I bought a sword and my money disappeared and the sword wasn't there. Fix it, this game is unplayable."

Good: "Shop: gold resets to 0 and purchased weapon is missing when buying with a full inventory. Steps: 1. Fill inventory to capacity. 2. Open shop. 3. Buy any weapon. Expected: purchase is blocked or gold decreases normally. Actual: gold goes to 0, no weapon appears, reopening the shop shows the purchase in history. Environment: PC, build 0.9.4, English. Frequency: 3 out of 3 attempts. Screenshot attached."

Same bug, same finder, completely different cost to the team.

Is there a template you can copy?

There is and simple beats clever:

```

Title: [Area]: behavior under condition

Environment: platform, OS, build ID, relevant settings

Steps:

1. ...
2. ...
3. ...

Expected: ...

Actual: ...

Frequency: always / X out of Y attempts

Notes/Attachments: screenshots, clips, related reports

```

Use it for every session until it's reflex and your speed won't drop, it'll rise. On platforms like PlaytestQuest, structured reports are exactly what developers rate highly and that quality feedback feeds the Fame points that build your tester reputation over time.

If you want to practice the formula on real unreleased games, new games or demos sign up at PlaytestQuest and write your first report against the template above. Precision is a habit and habits start with one session.