“The cart is broken” may accurately express frustration, but it leaves the next person with almost the whole investigation still to do. Which cart, which action, and which result? A useful bug report reduces those unknowns enough for someone else to observe the failure.
The goal is not a long document or an early theory about the cause. It is a clear route from a known starting state to a result that differs from the intended behavior.
Name the visible failure
Use a title that identifies the action and result. In a hypothetical shop application, “Cart quantity returns to one after page reload” is more informative than “Cart problem.” It describes what happened without claiming that a database, cache, or network request caused it.
Keep one report centred on one issue. If a checkout also has a separate visual problem, that may deserve its own report. Combining unrelated failures makes reproduction and later verification harder, because fixing one does not establish whether the other is resolved.
Specify the starting state
A developer cannot reproduce a journey that begins halfway through your account history. Describe the relevant setup: whether the user is signed in, the role they have, the application build, and any configuration necessary for the failure.
For the cart example, use a test account and a dummy product. State whether the cart begins empty and whether the product allows a quantity greater than one. Those details matter more than an exhaustive list of everything installed on your computer.
Include browser and operating-system information when relevant, particularly for a web issue. Use the versions you tested, not an assumption that “latest” means the same thing to everyone. If an environment detail is unknown, mark it as unknown.
Write actions someone can follow literally
Run through the sequence again if it is safe to do so. Record the controls used and the values entered. Avoid phrases such as “use the cart normally,” which require the reader to reconstruct your habits.
A newly written example might contain these steps:
- Sign in with the prepared test account and open an empty cart.
- Add one unit of the dummy product.
- Change its quantity to three and select the update control.
- Wait until the cart displays a quantity of three.
- Reload the page using the browser’s reload control.
These are hypothetical steps, not a report of a real shop failure. In your actual report, preserve any action required to trigger the behavior. Remove an action only after checking that the problem still occurs without it.
Separate expected behavior from observation
Describe the expected result using the relevant requirement or agreed behavior. In the example, that might be that the confirmed quantity remains three after reloading. If the requirement is uncertain, say so and ask for clarification instead of presenting a preference as an established defect.
Then describe the actual result independently: the cart displays one after the reload. Include any associated message and whether the underlying action completed, where that is known. Do not turn the observation into “the server lost the update” unless investigation has established that cause.
A screenshot can show the visible state, but it cannot replace the steps leading there. A reduced demonstration is especially useful for browser problems because it removes unrelated code and makes the behavior easier to inspect.
Record uncertainty and frequency
If the issue is intermittent, report what you actually observed. “Occurred on two of five attempts in this test session” is clearer than “sometimes.” Include differences you noticed between successful and failing attempts without treating them as proven explanations.
If you know a previous build worked, record that build and how you checked. If you have not tested other browsers or devices, do not imply that the failure affects them. Honest boundaries save investigation time.
Share evidence deliberately
Review screenshots, recordings, logs, and request details before attaching them. Remove personal information and secrets that are unnecessary for reproduction. Use approved private channels for evidence that genuinely needs restricted access.
Keep the evidence connected to the report. Identify which step a screenshot shows and which error belongs to the failing attempt. A large unexplained log file can hide the useful clue.
Search for an existing report, follow the project’s template, and answer follow-up questions with new observations. Structured issue forms can help collect the details consistently. The finished report should let a person who was absent from the original failure try the same path and know what result to look for.