Bug Report Builder

A bug report succeeds when someone else can follow it and see the same problem. Most failures are not about the bug but about the report: missing steps, no version, an unclear complaint such as “checkout is broken”. This builder turns the details into a structured report, in the order developers look for them, so that the first reader does not have to ask follow-up questions.

What to capture

Start with a short title that names the problem and where it happens: “Checkout button does nothing after applying a coupon”. Choose a severity. Critical means a crash, data loss or a security problem. High is a major feature broken with no workaround. Medium is broken with a workaround, and low is cosmetic. State how often it happens: every time, often, sometimes or seen once. Optionally name the area or component.

The environment tells a developer where to look: the app or build version, the operating system and device, and the browser and its version. Then write the steps to reproduce, one per line, starting from a known state. Say what you expected and what actually happened.

Optional evidence

The logs box takes error messages and log lines, which are printed as plain lines so they stay readable. Attachments names screenshots, recordings or files. The workaround box helps others carry on and shows that you have thought about impact. Notes holds anything else, such as “not reproducible without a coupon”. Sections with no content are left out.

How the report is laid out

The title comes first, followed by a small table with severity, frequency, area and the environment details. “Steps to reproduce” is a numbered list. “Expected result” and “Actual result” are short paragraphs, then logs, attachments, workaround and notes. The result can be copied as text or downloaded as Markdown for an issue tracker, or as PDF or Word for a ticket attachment.

A worked example

The sample is a checkout bug in version 4.12.1 (build 2381) on Android 14, Pixel 7, in Chrome 130. It is rated high and happens every time, in the Checkout area. The four steps are: add any item to the cart, open the cart and enter the coupon SAVE10, tap Apply (the price updates correctly), and tap Proceed to checkout. The expected result is that the checkout page opens with the discounted total. The actual result is that nothing happens, with no spinner and no error message. The log line is “Uncaught TypeError: Cannot read properties of null (reading “id”) at checkout.js:214”, the attachment is a screen recording, the workaround is to remove the coupon, proceed and enter it on the payment page, and the note says it is not reproducible without a coupon.

Habits that help

Reproduce the bug yourself before reporting it, and try to find the shortest set of steps. Check whether it happens on another device or in a private window, which can reveal whether an extension or cached data is involved. Search the tracker for duplicates. Describe what you saw, not what you think the cause is, unless you have evidence.

Limits

The tool formats what you tell it; it cannot test the software or confirm that the steps work. The severity labels are common conventions, and your team may use a different scale or priority system. Nothing you type is uploaded or saved.

Related tools

• PRD Template Builder documents the intended behaviour that a bug report compares against.
• Incident Postmortem Builder takes over when a bug has caused an outage and needs a review.
• SOP Builder writes down a repeatable procedure, such as how to triage reports.
• Markdown Editor lets you refine the report if you paste it into an issue tracker.