How to Write Actionable Bug Reports

A useful bug report gives another person enough information to reproduce a problem and decide what to do next. The central question is simple: under these conditions, what happened, and how does that differ from the agreed behavior?

Start with evidence you can explain. A screenshot, a confident diagnosis, or an urgent title cannot replace a clear account of the failure. Mozilla’s reporting guidance emphasizes descriptive titles, specific reproduction steps, environment details, and a usable test case. Mozilla: Filing good bugs

Capture the smallest reproducible case

Reproduce the issue before simplifying it. Record the original account state, input, build, browser, and page. Then remove unnecessary steps one at a time. If removing a step makes the failure disappear, that step may matter.

For an intermittent issue, keep the attempts visible. “Observed twice in ten attempts” gives a reviewer more information than “sometimes broken.” Record any difference between successful and unsuccessful attempts without treating a correlation as a cause.

Keep unrelated symptoms in separate reports unless there is evidence that they belong together. Two errors appearing on the same screen may need different owners, fixes, and verification steps.

Use a report structure that preserves the facts

The following example is fictional:

Title: Profile saves show success but sometimes discard the changed phone number.
Environment: Training build 1.4; browser and operating-system versions recorded.
Precondition: Signed in with a synthetic profile containing an existing phone number.
Steps: Open Profile, change the phone number, select Save, then reload the page.
Expected: After a successful save, the new number remains.
Actual: The previous number appears after reload in two of ten attempts.
Evidence: A short recording shows one failed attempt; a result table records all ten.
Impact: A user may believe their contact details were updated when they were not.
Unknown: The cause has not been established.

This format separates the contract from the observation. If the expected behavior is unclear, link the requirement you used or mark the question for clarification. Do not quietly invent a rule.

Explain impact and suggest a priority

Describe the affected task, the people or situations exposed, any workaround, and the consequence of leaving the issue unresolved. Use the team’s severity and priority definitions rather than assuming that every workspace uses the same scale.

For example, a missing success message and a silently discarded update can look similar at first. Their consequences differ. Explain that difference with the observed behavior, not an exaggerated label.

A suggested priority is useful when its rationale is visible. The final scheduling decision may also depend on release timing, affected scope, and other work.

Attach evidence that is safe to share

Capture only what the report needs. Crop unrelated windows, use synthetic records where possible, and remove credentials, tokens, and personal details from attachments.

Check recordings as well as screenshots: a browser address bar, notification, or developer panel may reveal information outside the intended scope. If a real secret has already been shared, report the exposure through the approved process; editing the attachment does not undo prior access.

Keep the issue useful through verification

Put the report in the appropriate project or team, search for an existing issue, and link related requirements or tests. Jira supports different work-item types, while Linear issues belong to one team and use that team’s workflow. Follow the local setup when assigning and updating the report. Atlassian: Jira basics, Linear: Create issues

After a fix, record the build tested, the steps repeated, the outcome, and any remaining concern. If the environment is unavailable, mark verification blocked.

Before you submit

Can someone follow the steps without guessing?
Are expected and actual results separate?
Does the evidence match the stated build and data?
Are frequency, impact, and unknowns stated honestly?
Are sensitive details removed?
Is the next owner or action clear?

Writing actionable bug reports