What are the most important fields in a bug report?

A clear title, exact steps to reproduce, expected vs actual behavior, and environment (browser, OS, app version). Everything else — screenshots, console logs, network traces, DOM session replay — is supporting evidence that shortens repro time.

How detailed should "steps to reproduce" actually be?

Detailed enough that a developer with no context can reproduce the bug on first try. That usually means 4–8 numbered steps starting from a known state (logged out, fresh tab, specific URL). If a step requires data setup, link the seed or describe it.

Do I need to attach a video or session replay?

For visual bugs, layout shifts, race conditions, or "it works on my machine" issues — yes, every time. A 30-second rrweb session replay with the DOM, console, and network captured replaces 20 minutes of back-and-forth Slack messages.

What is the difference between a bug report and a user story?

A bug report describes unintended current behavior that needs to change back. A user story proposes new behavior that doesnt exist yet. They share fields (description, acceptance criteria) but the bug report adds the critical "expected vs actual" plus reproduction steps.

When should I file a bug vs send a Slack message?

Always file the bug — even if you also send a Slack message. The ticket is the durable artifact (searchable, linkable from a PR, traceable to a release). Slack is for getting attention; the bug tracker is for accountability.

How to file a bug report developers actually want to fix

A great bug report has 6 things — in this order

A great bug report leads with the title and the steps to reproduce, then layers on evidence (screenshot or video, console + network logs, environment, expected vs actual). Get those six fields right and developers stop bouncing your tickets back with "need more info."

Key takeaway

The single best predictor of a fast fix is whether a developer can reproduce the bug on first try. Everything else in this guide exists to make first-try repro possible.

Background — why so many bug reports fail

Most bug reports fail one of three ways:

Missing repro steps. A vague "the page broke" with no path to reproduce sends the developer hunting through your account history before they can even start.
Wrong altitude. Reports either over-describe ("on Tuesday I clicked the green button while listening to Spotify…") or under-describe ("checkout broken").
No evidence. When something is intermittent, race-condition-y, or visual, words alone cannot convey what the user saw.

A 2025 Atlassian survey found engineering teams spend an average of 22 minutes per ticket just clarifying repro steps before they can begin work. That's the cost of bad reports — and it scales linearly with team size.

The 6-field structure

1. Title — searchable + specific

A good title is the search query your future self would type to find this bug. Bad: "checkout broken." Good: "Stripe Checkout fails with 'card_declined' on prepaid cards over $50."

2. Steps to reproduce — numbered, from a known starting state

1. Sign in as a free-tier user
2. Open https://app.example.com/projects/new
3. Type "Test" in the Name field
4. Click Save
   → Actual: button spins forever
   → Expected: project is created and you're redirected to /projects/<id>

Numbered steps. Starting state explicit. Click targets unambiguous. Expected vs actual stated inline at the failure point.

3. Expected vs actual

The two-line "→ Actual / → Expected" pattern above is the most underrated bug-report convention. It forces you to articulate the intent of the feature, not just the symptom. That alone often catches "this is actually working as designed" disagreements before they become Jira ping-pong.

4. Environment

Browser + version (Chrome 137, Firefox 128, Safari 18.4)
OS + version
App version (commit SHA if available, release tag otherwise)
Device (desktop / mobile / tablet, viewport size if responsive bug)
Network conditions (only if relevant)

If your bug reporter tool autocaptures these — and it should — you can skip this section entirely.

5. Evidence — screenshot, video, or session replay

Screenshot for static visual bugs (alignment, contrast, typo).
Video / GIF for state changes you can describe.
Session replay for race conditions, intermittent failures, or "it works on my machine."

Pro tip

A 30-second rrweb session replay captures the DOM tree, console logs, and network requests all at once — synced to the user's actions. It's not a video; you can pause, scrub, and inspect any element at any timestamp.

6. Console + network + state

Attach (or, better, autocapture):

Console errors and warnings from the failed session
Network HAR for the relevant requests (status codes, payloads, headers)
Local storage / cookies / Redux/Zustand store snapshot if the bug is state-related

Common mistakes

"Can you DM me your account credentials so I can reproduce?" — never. Use a shareable replay or a seeded test account.
Screenshots taken on a 5K display, viewed by a developer on a 13" laptop. Annotate the region of interest with arrows or a crop.
One ticket, multiple bugs. Split. Each bug gets its own lifecycle.
"Sometimes it doesn't work." "Sometimes" is not actionable. File when you can reproduce; if you can't, capture the replay and file once it recurs.
No priority. State your perceived severity ("blocks production checkout" vs "minor cosmetic on settings page"). The triager may downgrade, but they need your signal.

Live demo: anatomy of a BugMojo capture

When a teammate hits a bug in your app with the BugMojo extension installed, they don't fill out a form — they highlight the broken element, type one sentence, and submit. BugMojo attaches:

The last 30 seconds of DOM mutations as an rrweb replay
Every console message during that window
Every network request (status, payload, headers — with PII auto-redacted)
Browser, OS, viewport, page URL, build SHA
A direct link into your issue tracker (Jira, Linear, GitHub Issues)

Next steps

Get the template. Copy this 6-field structure into your team's bug-report template in Linear / Jira / GitHub Issues. Make it the default.
Install a capture tool. Whether it's BugMojo, Jam, or a homegrown extension, autocapturing the environment + console + network is the single biggest workflow upgrade a QA team can make.
Run a one-week experiment. Pick a sprint, require every bug report to include the 6 fields, and measure ticket roundtrip time before and after. The numbers tell the rest of the story.

Ready to ship bug reports your developers will actually thank you for? BugMojo captures DOM replay, console, and network in a single Chrome click — install free in under 30 seconds.

Frequently asked questions

Sources

How to Report Bugs Effectively — Simon Tatham (PuTTY) (1999, updated 2025)
IEEE 829: Standard for Software and System Test Documentation — IEEE (2008)
rrweb — open-source session replay — rrweb-io (2025)

A great bug report has 6 things — in this order

Key takeaway

The single best predictor of a fast fix is whether a developer can reproduce the bug on first try. Everything else in this guide exists to make first-try repro possible.

Background — why so many bug reports fail

Most bug reports fail one of three ways:

Missing repro steps. A vague "the page broke" with no path to reproduce sends the developer hunting through your account history before they can even start.
Wrong altitude. Reports either over-describe ("on Tuesday I clicked the green button while listening to Spotify…") or under-describe ("checkout broken").
No evidence. When something is intermittent, race-condition-y, or visual, words alone cannot convey what the user saw.