· 9 min read
How to write a bug report developers actually act on
A practical template for writing bug reports that get triaged and fixed faster, with examples, anti-patterns and the fields every report should include.
A great bug report is the difference between a fix shipped today and a ticket that drifts for three sprints. The pattern is simple: describe what happened, what should have happened, and how to reproduce it — with enough context that an engineer can recreate the failure on the first attempt, on their own machine, without messaging you back.
Most teams already know this in theory. In practice the reports that land in their tracker are one-line cries for help: "login broken", "page is weird", "doesn't work on mobile". This guide is the template, the checklist, and the small habits we have seen work across hundreds of teams using dontslowme.
The five questions every report must answer
Skip any of these and you force the engineer to come back asking. That round-trip is where most of the wasted time lives — not in the fix itself, but in the days between report and clarification.
- What did you do? Steps to reproduce, in order, one action per line.
- What did you expect to happen?
- What actually happened? Include the exact error text, status code, or visual glitch.
- Where did it happen? URL, screen, environment, browser, device, app version.
- Evidence: screenshot, screen recording, network log, console output.
A template you can copy
Use the same structure every time. Consistency makes triage scannable. After a week, your team starts reading reports in the same order on every ticket, and triage time drops by half.
Title: Save button does nothing on /invoice/new after adding more than 10 line items Environment: Chrome 140 · macOS 15.2 · build 2026.04.11-prod · role: Accountant Steps: 1. Log in as accountant@acme.test 2. Open /invoice/new 3. Add 11 line items (any product) 4. Click Save Expected: invoice saved, redirect to /invoice/:id Actual: button shows spinner for 1s, then nothing. No toast. No URL change. Evidence: screenshot + 8s screen recording attached. Console shows "POST /api/invoice 500". Network tab shows response body "line_items exceeded validation". Impact: blocks month-end billing for ~15 accountants.
Screenshots and video beat words
A 10-second screen recording carries more information than three paragraphs. Capture the actual click path, including hover state and the moment of failure. Annotate with a red arrow on the broken element — both macOS Markup and the Windows Snip tool do this in two clicks.
In dontslowme you can paste screenshots straight into a bug with Ctrl/Cmd + V on any open card, or attach a recording from the same panel. No save dialog, no file picker, no "where did I put that PNG".
When a screenshot is not enough
- Timing-dependent bugs — "the dropdown closes too fast" needs video.
- Sequence bugs — three clicks in a specific order to reproduce.
- Animation jitter — single frames hide the problem.
- Audio glitches in players — record with system audio enabled.
Severity, priority, and the trap of inflation
Severity is a property of the bug itself: how much damage it does when it fires. Priority is a team decision about when to fix it. They are not the same, and conflating them is the most common reason a queue becomes unworkable.
If everything is Critical, nothing is. Reserve Critical for data loss, security incidents and complete outages. Most bugs are Medium, and that is fine — Medium is not a failure rating, it is the honest default.
Common anti-patterns
- "It doesn't work" — what doesn't, on what page, after what action?
- Filing several issues in one ticket — split them up so each can be triaged and assigned independently.
- Missing build or version — "latest" stops being latest tomorrow.
- Screenshot of the whole desktop with the bug in a 200px corner — crop to the broken element.
- Reporting in a chat thread that scrolls away — file it in the tracker first, link it in chat.
Triage tips for the receiving team
Acknowledge within one working day, even if you cannot fix yet. Assign severity, priority and an owner. Move status from New → In progress → Review → Done so the reporter always knows where things stand without asking. Status history that anyone can read at a glance is one of the most underrated trust-builders between dev and QA.
If a report is incomplete, do not close it — comment with the missing fields and bounce it back to the reporter. Closing as "needs info" teaches the team that effort is wasted. Bouncing teaches them what good looks like.
How dontslowme helps
Every dontslowme bug card already has the five questions baked in: title, description, environment, evidence, status. Paste a screenshot, drop in a recording, pick a project and a category — you are done in under 60 seconds. Status history is visible on every card so reporters never have to ask "is this still being looked at?".