PoliteTools

Product & QA

Bug Report Generator

A bug report that a developer can act on needs four things: what you did, what you expected, what happened instead, and where. This builds that structure, tells you which parts are still missing, and gives you Markdown to paste into your tracker.

nothing you type is sent anywhere

Loading tool…

How to use Bug Report Generator

  1. Write a title describing the symptom and the condition, not just the area.

  2. List the steps in the order someone else would follow them.

  3. State the expected result and the actual result separately.

  4. Add the environment and any notes, then copy the Markdown.

Why most bug reports get sent back

The commonest reason a bug is not fixed quickly is not difficulty; it is that the report does not contain enough for anyone to reproduce it. A developer receiving "checkout is broken" has to spend their first hour recovering information the reporter already had.

Four things prevent almost all of that: what you did, what you expected, what actually happened, and where. Everything else in a good report is elaboration on those.

It is worth writing them in that order too. Reporters who start with their theory about the cause frequently bury the observation, and the theory is usually wrong in a way that sends the investigation sideways for a day.

Separating expected from actual

These are recorded separately because the gap between them is the bug, and stating both makes the disagreement explicit. It occasionally resolves the ticket outright: sometimes the software is behaving as specified and the expectation was wrong, which is a specification problem rather than a code problem and gets fixed somewhere completely different.

It also protects against a subtle failure, where a developer fixes what they assumed you meant. If the expected result is written down, the fix can be checked against it rather than against a recollection of a conversation.

Be concrete in both. "The discount should work" is not an expected result; "the total should drop to ₹900 and the discount should appear as a separate line" is, and it can be verified by someone who has never seen the feature.

Reproduction steps and the detail people leave out

Write steps someone unfamiliar with the bug could follow without asking a question. Include the starting state, the exact data used, and anything about the account or configuration that matters.

The most frequently omitted detail is the condition that makes the bug appear. A step reading "log in" hides everything when the defect only affects accounts of a particular type, on a particular plan, or with a particular history. That condition is often the entire finding, and the reporter usually knows it without realising it is unusual.

For intermittent bugs, say so explicitly and estimate the frequency. An intermittent bug reported as reproducible costs a developer an afternoon proving it is not, and that time comes out of fixing it.

Severity, and the inflation problem

Severity should reflect impact on users, not the reporter's frustration. A blocker stops work entirely with no workaround. Critical breaks a core path but has one. Major is a real defect in a working feature. Minor is something people can live with, and trivial is cosmetic.

Inflating severity works once. When everything in the queue is critical, severity stops carrying information, triage falls back to whoever asks most persistently, and genuinely urgent things get lost among the merely annoying.

It is also worth separating severity from priority, which are routinely conflated. Severity is how badly it breaks; priority is when it will be fixed. A trivial typo on the pricing page can be high priority and low severity at the same time, and a system that cannot express that will keep having the same argument.

Frequently asked questions

Why separate expected from actual?

Because a report saying only "the discount does not work" leaves a developer guessing at what working would look like. Stating both makes the disagreement explicit, and it occasionally resolves the ticket immediately — sometimes the behaviour is correct and the expectation was wrong, which is a specification bug rather than a code bug and is fixed somewhere else entirely.

How specific do the reproduction steps need to be?

Specific enough that someone who has never seen the bug can follow them without asking a question. Include the starting state, the exact data used, and anything about the account or configuration that matters. The commonest failure is a step like "log in" when the bug only appears for accounts of a particular type — that detail is the whole finding.

What if the bug is intermittent?

Say so explicitly and give your best estimate of frequency, because it changes how the bug is investigated. Include everything you can about the times it did happen — timestamps, what else was running, whether it followed a deploy. An intermittent bug reported as reproducible wastes a developer's afternoon proving it is not.

How should I choose a severity?

Rate the impact on users, not your frustration. A blocker stops work entirely with no workaround. Critical breaks a core path but has one. Major is a significant defect in a real feature. Minor is a defect people can live with, and trivial is cosmetic. Inflating severity is a short-term win and a long-term cost: once everything is critical, nothing is.

Is my bug data sent anywhere?

No. The report is assembled in your browser and nothing is transmitted. Bug reports frequently contain account identifiers, internal URLs, staging credentials and stack traces, which is exactly why this one does not upload.

What next