How to Write a Bug Report Developers Can Act On

A bug report is actionable when someone else can reproduce the problem from it without asking you anything. That is the whole standard. Everything else, including severity labels and screenshots, is secondary to whether a developer can make the bug happen on their own machine.

Reports that fail this test do not get fixed slowly. They get a clarifying question, then sit for four days waiting for your reply, then get closed as unreproducible.

The Four Required Parts

Steps to reproduce. Numbered, starting from a known state, specific about data. “Log in as a standard user, open the Reports tab, select date range 1 to 31 July, click Export.”

Expected result. What should have happened. This sounds redundant and it is not. Half of reported bugs turn out to be misunderstandings of intended behavior, and stating your expectation surfaces that immediately.

Actual result. What did happen, precisely. Not “it breaks.” Does it error, hang, return wrong data, or silently do nothing? Include the exact error text rather than a paraphrase.

Environment. Browser and version, operating system, app version, account type, and whether it is production or staging. Bugs that only occur on one browser or one account tier are extremely common, and this is what identifies them.

The Rewrite

Before:

The export is broken again. It was working fine last week. A few of us have tried it and it doesn’t work for anyone. Can someone look at this urgently please, the client is asking.

After:

Summary: CSV export returns an empty file for date ranges spanning a month boundary.

Steps:

1. Log in as a standard user (tested with two accounts, both standard tier).
2. Open Reports, select date range 28 June to 5 July.
3. Click Export CSV.

Expected: CSV downloads with rows for the selected range.

Actual: CSV downloads with headers only, 0 rows. No error shown. Console shows a 200 response with an empty data array.

Environment: Chrome 141, Windows 11, app v4.2.1, production.

Notes: Ranges inside a single month work correctly. 1 to 31 July returns 4,102 rows as expected. First noticed 24 July; last known working 17 July.

The second version contains a diagnosis. “Works within a month, fails across a boundary” narrows the problem to a specific piece of logic, and a developer can often locate it before reproducing anything.

Isolate Before You Report

The most valuable thing a reporter can do is narrow the conditions. Five minutes of testing saves an hour of someone else’s.

Does it happen in another browser? With another account? With a different date range or a different record? On staging as well as production? Every one of those answers eliminates a class of causes.

“It fails for user A but not user B, and both are standard tier” is worth more than any amount of urgency language.

Frequency and Timing Matter

State whether it happens every time or intermittently. Intermittent bugs are a completely different investigation, and mislabeling a flaky one as consistent wastes a day.

Give the date you first saw it and the last date it worked, if you know. That window maps directly to a set of deployments, which is often the fastest route to the cause.

Severity Honestly

Every reporter believes their bug is urgent. Inflating severity works once, and after that your reports get discounted along with everyone else’s.

Describe impact factually and let the triage process decide: how many users are affected, is there a workaround, is data being lost or corrupted, is money involved. “Blocks month-end reporting for the finance team, no workaround, needed by 31 July” is more persuasive than “critical.”

Data loss and security issues genuinely are different, and should be flagged as such and reported through the right channel rather than a public tracker.

Writing It Up Quickly

The reason people write bad bug reports is that they are in the middle of something else and the good version takes ten minutes.

A Wrivio Context for this could say:

Rewrite these notes as a structured bug report with the headings Summary, Steps, Expected, Actual, Environment, and Notes. Neutral technical register, no urgency language and no blame. Convert vague statements into specific ones where the detail is present in my notes. If a required detail is missing, add a line under Notes saying which information is missing rather than inventing it. Keep every version number, error message, date, and figure exactly as written.

Press Ctrl+Shift+Space, paste your rough notes, and run it. The instruction about missing information is the important one: you want the tool to flag that you never recorded the browser version, not to guess a plausible one. A fabricated environment detail sends someone down the wrong path for an afternoon.

If the report contains customer data, account identifiers, or internal system details, run it in Local mode so none of that leaves the machine.

Common Questions

Should I include a screenshot?

For visual and layout bugs, yes. For logic bugs, the error text and console output are more useful. A screenshot of an error message is worse than the text, because nobody can search it.

What if I cannot reproduce it consistently?

Say so explicitly and give your best estimate of frequency. Include what you were doing before it happened, since intermittent bugs often depend on prior state.

Where do logs go?

In a code block or an attachment, not pasted into the summary. Include timestamps so they can be matched against server logs.

Should I file a bug or ask in chat first?

File it. Chat questions disappear; tickets are searchable and connect to the fix.

Download Wrivio for Windows to turn rough debugging notes into a structured report without leaving the tracker.