Bug Report Template: What Makes One Useful

Contributor
Mar 18
5 min read

The difference between a useful bug report and a useless one isn't length. It's whether an engineer can act on it without asking three follow-up questions. Useful reports get fixed faster because they minimize back-and-forth; useless ones bounce around for days as everyone tries to figure out what happened.

This guide is a working template and the discipline that makes it useful.

The Working Template

**Title:** [Short, specific summary of the bug]

**Environment:**
- Build/version: [version number or commit]
- OS / Browser: [if relevant]
- Account/User: [if relevant, e.g., user ID or role]

**Steps to Reproduce:**
1. [First action]
2. [Second action]
3. [Third action]

**Expected:**
[What should happen]

**Actual:**
[What does happen]

**Frequency:**
[Always / Sometimes / Once]

**Severity:**
[P0 / P1 / P2 / P3]

**Additional Info:**
- Screenshots/video
- Error messages or logs
- Workarounds (if any)
- When did this start
- Related tickets

That's it. Most reports fit on one screen.

The Title

A bug title should let someone scanning a list decide if the bug is relevant to them.

Bad: "App is broken," "Bug in checkout," "Error message"

Good: "Checkout fails with 500 error when address contains apostrophe," "Mobile nav menu doesn't close after selecting item," "Date filter shows yesterday's data after 5pm UTC"

A specific title saves dozens of question-and-answer cycles.

Environment

Many bugs are environment-specific. Listing the environment lets the engineer reproduce.

Build/version: the most important field. Many bugs are already fixed in newer versions.
OS / Browser: for client-side bugs
Account/User: sometimes bugs only affect users with specific properties

If the environment doesn't seem relevant, list it anyway. The engineer will judge.

Steps to Reproduce

The most undervalued section. If steps are clear, the bug is half-solved.

Each step:

Numbered
Specific (not "do some stuff")
Executable by someone unfamiliar with the bug

Bad:

1. Try to log in
2. It doesn't work

Better:

1. Open Chrome 120 in incognito mode
2. Go to app.example.com/signin
3. Enter "test@example.com" / "ValidPassword123"
4. Click "Sign in"

If you can't reproduce reliably, say so explicitly. "I've seen this twice but can't reliably reproduce" is more useful than fabricated steps.

Expected vs. Actual

Two parallel statements, separated.

Bad: "It doesn't work when I try to save."

Good:

Expected: Form saves and shows confirmation message "Settings updated" Actual: Form spinner runs for 10+ seconds, then a console error appears, and no confirmation is shown. Refresh shows original data unchanged.

The expected/actual format forces clarity. "It doesn't work" is meaningless; what should have happened versus what did happen is actionable.

Frequency

Bugs that happen every time and bugs that happen rarely need different responses.

Always: reproducible, can be fixed deterministically
Sometimes: intermittent, may need investigation to find the trigger
Once: seen one time; may not warrant immediate action if not reproducible

For intermittent bugs, include any patterns you've noticed. "Always on Tuesdays" or "Only on iOS" is signal.

Severity vs. Priority

These are different.

Severity: how bad is the impact?
Priority: how urgent is the fix?

A bug can be high severity (data loss) but low priority (only affects 3 users on an unsupported old browser). Or low severity (cosmetic) but high priority (visible to a major customer in a demo).

Many trackers conflate them. If yours does, default to severity and note priority context in the description.

Screenshots and Video

For visual bugs, a screenshot saves a paragraph of description. For interaction bugs, a short video saves several paragraphs.

Patterns:

Annotate screenshots if the issue isn't obvious — circle the affected element
Crop to the relevant area; full-screen screenshots add noise
Keep videos short — 10-30 seconds. Longer videos require seeking.

For privacy: blur or replace personal data.

Error Messages and Logs

The most diagnostic information is usually the exact error.

Include the verbatim text, not a paraphrase
Include stack traces if available
For server-side issues, include a request ID or timestamp so engineers can find the corresponding logs
For console errors, include the full message

When Did This Start

Bugs that didn't exist last week and exist this week point at a recent change. Including the timing helps engineers narrow the suspect commits.

"I noticed this morning"
"After yesterday's deploy"
"Last worked Friday"

If you don't know, leave it blank. Don't guess — wrong guesses send the engineer down wrong paths.

Workarounds

If there's a way to avoid the bug, document it. Two reasons:

Helps support handle inbound questions while the fix is pending
Helps engineers understand the boundaries of the bug

Example: "Workaround: removing apostrophes from address before submitting succeeds."

What to Skip

A few things commonly included in bug reports that don't help.

Speculation about the cause. "I think this is because the database query is wrong." Engineers will figure out the cause; let them. Speculation in the report sometimes biases the investigation.

Long history of similar issues. "This is similar to the bug we had in 2023..." Link to the related ticket; don't recount the history.

Marketing language. "This is impacting our most important customers." Severity should capture the impact; superlatives don't.

Demands. "This needs to be fixed today." Priority comes from triage, not from report demand. Provide impact information; let the team prioritize.

Anti-Patterns

The vague report. "App is slow." No environment, no steps, no specifics. Engineers can't do anything with it.

The novel. Five pages of context, embedded screenshots, history of conversations. Important information is buried.

The catch-all. One report covering three different bugs. Should be three reports.

The duplicate. Same bug reported four times because the reporter didn't search. Compounds investigation.

The not-a-bug. A feature request filed as a bug. Different process, different priority.

Triaging Bug Reports

A separate discipline from writing them, but worth mentioning.

Triage looks at each report and assigns:

Severity (impact)
Priority (urgency)
Owner (or team)
Status (confirmed, needs more info, duplicate, etc.)

Most bug reports need triage within 24-48 hours. The pipeline of un-triaged bugs is where reports go to die. Establish a regular triage cadence — usually daily for active teams.

Auto-Capturing Information

For repeat reporters (support team, QA, internal users), much of the template can be auto-captured.

Browser extensions that grab environment automatically
In-app feedback widgets that include build version and user ID
Error monitoring tools that capture stack traces and console output

The less the reporter has to type, the more reports you get. The more reports you get with good data, the faster bugs are diagnosed.

A Worked Example

**Title:** Cannot save profile when display name contains accent characters

**Environment:**
- Build: v4.7.2 (production, deployed 2026-05-22)
- Browser: Chrome 121 on macOS 14.4
- Account: test+accents@example.com (Standard user)

**Steps to Reproduce:**
1. Sign in
2. Navigate to /settings/profile
3. Change "Display name" field to "Renée"
4. Click "Save"

**Expected:** Profile saves, success message shows, name updates in header

**Actual:** Spinner shows for 8-10 seconds, then "Server error - try again" appears. Name is not updated. Refresh confirms no change.

**Frequency:** Always (tested 5 times with various accented characters)

**Severity:** P2 - affects users with names containing common European characters

**Additional Info:**
- Screenshot attached (error state)
- Console error: "ValidationError: invalid characters in display_name"
- Network tab: PUT /api/v1/profile returns 400 with body {"error": "invalid_field", "field": "display_name"}
- Workaround: removing accents allows save
- Noticed after yesterday's release; previously worked
- Related: TICKET-1842 (similar issue with addresses)

A report like this gives the engineer everything they need: reproducible steps, environment, observable evidence, and even a hint about the regression timing. The fix can start without follow-up questions.

Key Takeaway

A useful bug report has a specific title, environment, reproducible steps, expected vs. actual, frequency, severity, and supporting evidence. Most reports fit on one screen. Skip speculation about causes; provide observable facts. Auto-capture environment data where possible. Triage promptly — un-triaged bugs are dead bugs. The discipline of writing a good report is small; the time it saves is large.

ShiftQuality