How to write a bug report that separates symptom, evidence, and next check

A useful bug report separates the user-visible symptom, the evidence already collected, and the next check that would narrow the cause.

Many reports mix these layers into one paragraph: “the save button is broken, maybe the token expired, can someone check the server?” That is understandable, but it makes the receiver untangle observation from theory. A clearer report starts with what happened, then lists what was observed, then names one or two likely next checks without pretending the cause is already proven.

The symptom should be concrete. Say what action was attempted, what the user saw, and whether the result is repeatable. “Save failed after editing the billing address” is better than “profile page broken.” If a screenshot is included, add the text version too, because images are hard to search and may hide important timing or request details.

Evidence should include status code, response message, request id if safe, browser or client version, environment, account type, timestamp, and whether the same request works elsewhere. Keep private values redacted. If a command-line reproduction exists, include it. If it does not, say what prevented one.

The next check should be small. Examples: compare the same request with a different role, retry with a fresh token, remove optional body fields, test the same endpoint in staging, or verify whether the feature flag is enabled for that account. Avoid asking someone to “investigate everything.”

The goal is to make the report actionable without making it overconfident. A good report lets the next person either reproduce the failure or reject one hypothesis quickly.

How to write a bug report that separates symptom, evidence, and next check

// COMMENTS

ON THIS PAGE