In this insight
A useful bug report explains what you were trying to do, what happened, what should have happened and how somebody else can reach the same situation. A screenshot is evidence, but it rarely supplies all four answers.
That distinction matters when the person reporting a problem and the person fixing it do not share the same context. One sees an obvious mistake. The other sees an image of an unfamiliar screen. The missing information becomes another meeting, another guess or a fix to the wrong behaviour.
Begin with the interrupted task
Start with the work, not the proposed repair. Instead of saying make this button bigger, explain that you were reviewing a request on a phone and could not find the action needed to continue. The eventual solution might involve size, position, wording or a different interaction.
Describe the starting state. Were you signed in as an owner or a reviewer? Was the request a draft or already submitted? Had you just changed organizations? These details often determine which behaviour is correct.
You do not need to understand the implementation. You need to explain the interruption well enough that another person can recognize it. A plain-language account is more valuable than a confident technical diagnosis based on a guess.
Write the smallest reproducible journey
Consider a fictional scheduling app. The report says the new date disappears. A useful reproduction is more specific: open a saved appointment, choose another date, save, return to the list and reopen it. The previous date appears again.
Include what you expected: the saved appointment should show the new date. Then record what actually happened, including whether the page reported success. This separates a failure to save from a failure to display the saved value.
Try the sequence again if doing so is safe. A repeatable result helps, but an intermittent problem still deserves a report. Say that it happened once or only after switching workspaces. Do not present an uncertain pattern as a confirmed rule.
Attach evidence that preserves meaning
A screenshot can show the selected date, the page title and the message after saving. A short recording may reveal a transition that a still image misses. Attach only what is needed, and use fictional records when preparing examples for wider review.
Remove names, contact details, tokens and unrelated records before sharing. Cropping a screenshot can help, but it can also remove the state that explains the problem. Keep enough context to understand the task while excluding information that does not belong in the report.
Preserve the original observation separately from the later interpretation. If a builder discovers that the date was stored correctly but the list was stale, add that finding. Do not rewrite the first report to make it look as though the cause was known from the start.
Agree on what would prove the fix
A bug report becomes much more useful when it includes an acceptance check. For the appointment example: after saving and reopening, the selected date appears in both the detail view and the list. That is observable without reading code.
Add nearby cases that could break during the repair. What happens if the person saves twice, loses access while editing, cancels before saving or opens two versions at once? If changing a date sends invitations, verify which event causes delivery and that a retry does not send duplicates.
These checks should follow the risk, not become a ritual of testing everything. A visual spacing issue may not affect persistence or notifications. Say when a case does not apply. The goal is to identify meaningful boundaries, not to turn every report into a hundred-step document.
Keep feedback connected to the decision
Once the problem becomes a task, link it back to the original report and its evidence. Record who agreed on the expected behaviour. If the team chooses a different solution, explain why rather than leaving the reporter to discover the change later.
The completion message should say what was checked. Fixed locally, passed an automated test and confirmed in production are different statements. A person should not have to infer deployment from the word done.
This approach also improves AI-assisted work. An agent given a precise observation and acceptance criteria has a better target than one told to improve the screen. Human review still decides whether the change solves the original problem without creating a different one.
Model conversion exercise
Use this exercise with a real workflow and the people accountable for its outcome. Record disagreements as modeling questions instead of silently choosing an answer.
Write a report about a fictional appointment that fails to keep its new date. Include the goal, starting state, five or fewer reproduction steps, expected result, actual result and one screenshot description. Ask a teammate to follow it without asking questions. Record what they still needed to know, then add one regression check for a repeated save and one for a cancelled edit.