Bug Report

How to Write Bug Reports That Actually Get Fixed

The difference between a bug that gets fixed in a day and one that languishes for weeks usually isn't severity — it's the quality of the report. A clear, structured bug report reduces debugging time by giving the engineer exactly what they need to reproduce, diagnose, and fix the issue. A vague report ("checkout is broken") creates a back-and-forth that wastes everyone's time.

The Title Is a Summary, Not a Symptom

"Page crashes" tells the engineer nothing. "Checkout page freezes and clears cart when applying SPRING25 promo code" tells them exactly where to look, what triggers it, and what happens. A good bug title answers three questions: where (which page/feature), what (the behavior), and when (the trigger).

Reproduction Steps Are Non-Negotiable

"It happens on checkout" is not a reproduction path. Numbered steps from a known starting state are: "1. Add items to cart. 2. Go to checkout. 3. Enter SPRING25. 4. Click Apply." If the engineer can't reproduce it, they can't fix it. If your steps don't reproduce the bug consistently, note the reproduction rate — "happens ~3 out of 5 times" is useful information.

Expected vs. Actual Is the Contract

Every bug is a gap between what should happen and what does happen. State both explicitly. "Expected: promo code applies discount. Actual: page freezes and cart empties." This framing prevents debates about whether something is a bug or a feature. If the expected behavior is documented (in specs, designs, or user stories), reference it.

Environment Details Save Hours

"It works on my machine" is the most expensive sentence in software development. Browser, OS, device, app version, screen size — these details narrow the search space dramatically. A bug that only happens on Safari iOS points to a different root cause than one that's cross-browser. Include the environment even if you think it's irrelevant.

Severity Should Reflect Business Impact

P0-P4 is a framework, but the number alone doesn't create urgency. Pair the severity level with business context: "P1 — promo code is on the homepage banner, we're actively losing orders during the spring sale." This gives the engineering manager the information they need to prioritize correctly.

Attach Evidence

Console errors, network logs, screenshots, screen recordings — anything that gives engineers a head start on diagnosis. A console error like "TypeError: Cannot read properties of undefined (reading 'discount')" might be all an engineer needs to find the bug without even reproducing it.

Paste the Report, Get the Structure

Found a bug? Paste your messy Slack message, customer complaint, or personal notes into Struq. The Bug Report template extracts: title, severity, environment, reproduction steps, expected vs. actual behavior, logs, workaround, and impact scope. Send a structured report instead of a wall of text.