How to write a bug report developers actually read

Why most bug reports fail

A bug report fails when a developer cannot reproduce the bug. Vague titles, missing steps, no environment details, and no evidence all push the report into the "needs more info" pile — where it stays until someone closes it. The problem is rarely the bug; it is the report.

The anatomy of a good report

A report developers can act on has six parts:

• A specific title — what broke, and where: "Checkout fails with 'card declined' after entering a valid card", not "Payment broken".
• Steps to reproduce — numbered, starting from a known state, with no skipped assumptions.
• Environment — browser, OS, viewport, and any configuration that matters.
• Expected vs actual — what should have happened, and what actually did.
• Evidence — screenshot, recording, or console output showing the failure.
• Severity — how bad it is, so the team knows what to fix first.

Good vs bad examples

Bad: "The form is broken on mobile." — no steps, no device, no evidence, no severity.

Good: "On iPhone 15 (Safari, iOS 17), the contact form submits but the success message never appears. Steps: 1) open /contact on a 390px viewport, 2) fill all fields, 3) submit. Expected: success message within 2 seconds. Actual: button shows a spinner, then nothing; the network tab shows a 500 on /api/contact. Severity: major — blocks all mobile leads."

The second report takes two minutes longer to write and saves the developer twenty minutes of reproduction — and it gets fixed.

Severity classification

Severity is about impact, not emotion. A critical defect blocks the core flow for everyone; a major defect breaks a significant flow or a subset of users; a minor defect is cosmetic or edge-case. Classifying honestly — including saying when something is minor — builds the trust that makes urgent reports get taken seriously.

The format in practice

The published sample assessment on this site shows this format applied to a real product: severity-classified findings with reproduction steps and evidence, an area-by-area status summary, and a release recommendation. It is the same format Cypher QA delivers for bug reporting and QA documentation engagements.