How to write a bug report developers can fix on the first pass

TL;DR — A bug report gets fixed faster when it shows one specific problem, the exact steps to reproduce it, what you expected, what actually happened, and evidence like screenshots, timestamps, and URLs. The single most likely fix for a weak report is to replace vague phrases like "it broke" with a numbered reproduction path and the exact error text. Reading time: ~5 min

Goal

When you are done, you will have a complete bug report that a developer can reproduce without asking you basic follow-up questions, increasing the chance the issue is fixed on the first attempt.

Prerequisites

• Access to the app where the bug happens, with the same account and role that saw the problem (for example: admin, editor, customer)
• A place to submit the report: your agency's ticket portal, email thread, or issue form
• A way to capture evidence: built-in screenshot tool on your computer or phone
• The exact page URL(s) where the problem happens, if this is a web app
• The date, time, and time zone when the bug happened
• Your device and browser/app version
• If using a browser, one of these current browsers: Chrome, Edge, Firefox, or Safari
• Optional but useful: a private/incognito window (a browser session without old cookies/cache), and a second browser to confirm the issue

Steps

Step 1: Confirm it is a bug, not a one-time glitch

Do these checks before you write the report:

1. Reload the page once.
2. Repeat the same action in a private/incognito window.
3. If possible, repeat it in a second browser.
4. Try with one different user account that has the same role.

Exact browser paths:

• Chrome: Menu (⋮) → New Incognito Window
• Edge: Menu (...) → New InPrivate window
• Firefox: Menu (≡) → New private window
• Safari: File → New Private Window

What you should see when this step succeeds: you know whether the bug happens consistently, and you can say "happens every time" or "happened once and I could not reproduce it."

Step 2: Capture the exact page, time, and account context

Copy these values into a note before you submit anything:

Page URL:
Date:
Time:
Time zone:
Account email or username:
User role:
Environment: Production / Staging / Test

Use the literal page URL from your browser address bar. For the time zone, use the one shown by your device clock settings, for example America/New_York or UTC+1.

What you should see when this step succeeds: you have a filled-in context block with no blanks except fields that truly do not apply.

Step 3: Write the shortest possible title with the symptom

Use this title formula:

When I <action>, <thing> <wrong result>

Examples:

When I click Save on the invoice form, the page freezes on "Saving..."
When I reset my password, the email never arrives
When I export orders as CSV, the file downloads with blank rows

What you should see when this step succeeds: the title names one action and one visible failure, not a general complaint like "Website broken."

Step 4: Write exact reproduction steps as a numbered list

Use this template and replace the placeholders with your literal clicks and typed values:

1. Sign in as [account email or role].
2. Go to [full page name] at [full URL].
3. Click [exact button/link label].
4. Enter [exact value, or "leave blank"] in [field name].
5. Click [exact button label].
6. Observe [exact error text, wrong page, missing result, or freeze].

Bad example:

Tried to update settings and it failed.

Good example:

1. Sign in as editor@example.com.
2. Go to Settings at https://app.example.com/settings/profile.
3. Click Edit Profile.
4. Enter 555-0101 in Phone Number.
5. Click Save.
6. Observe the red message "Phone number is invalid" even though the field accepts the value.

What you should see when this step succeeds: another person can follow your steps exactly without guessing where to click or what to type.

Step 5: Add expected result and actual result

Paste this block into your report and fill in both lines:

Expected result:
Actual result:

Example:

Expected result: The profile saves and a green "Profile updated" message appears.
Actual result: The page stays on "Saving..." for more than 30 seconds and never completes.

What you should see when this step succeeds: the difference between correct behavior and broken behavior is obvious in one glance.

Step 6: Attach evidence that matches the steps

Add only evidence that helps reproduce or diagnose the bug:

- Screenshot of the full browser window, including the address bar if possible
- Screenshot of the error message
- Screen recording of the exact steps if the issue is about timing, animation, or a freeze
- Copied error text, exactly as shown
- Order ID / Invoice ID / Record ID, if one specific item fails

If the app shows an error code, copy it exactly, including punctuation and capitalization.

What you should see when this step succeeds: your report includes proof of the issue, and each attachment clearly matches one of your reproduction steps.

Step 7: Add impact and frequency in one line each

Paste these lines and fill them in:

Frequency: Every time / 3 out of 5 times / Once only
Impact: Blocks work / Workaround exists / Cosmetic only
Workaround: None / [exact workaround steps]

Example:

Frequency: Every time
Impact: Blocks work
Workaround: None

What you should see when this step succeeds: the team can prioritize the bug correctly without asking how serious it is.

Step 8: Submit using a copy-paste template

Use this exact template in your ticket portal, email, or issue form:

Title: When I [action], [thing] [wrong result]

Environment: Production / Staging / Test
Account email or username:
User role:
Page URL:
Date:
Time:
Time zone:
Browser/app and version:
Device/OS:

Steps to reproduce:
1.
2.
3.
4.

Expected result:

Actual result:

Exact error text:

Frequency:
Impact:
Workaround:

Attachments:
- screenshot.png
- screen-recording.mp4

What you should see when this step succeeds: your submitted report reads like a checklist someone else can follow from top to bottom.

Verify it works

Use this checklist before you send the report:

[ ] The title describes one bug, not several
[ ] The report includes a full page URL or exact screen name
[ ] The steps are numbered and can be followed literally
[ ] The expected result and actual result are both filled in
[ ] The exact error text is copied, not paraphrased
[ ] The date, time, and time zone are included
[ ] The browser/app version and device are included
[ ] At least one screenshot or recording is attached if the issue is visible
[ ] Frequency and impact are included

The report is ready when every box above is checked.

Common pitfalls

"It doesn't work" with no exact steps

Mistake: Writing a summary instead of a reproduction path.

Symptom it produces: The team replies asking "What did you click?" and the fix is delayed.

One-line fix: Replace the summary with a numbered list starting from sign-in and ending with the visible failure.

Reporting multiple bugs in one ticket

Mistake: Combining unrelated problems like login failure, slow dashboard, and missing export into one report.

Symptom it produces: One part gets fixed while the rest are missed or closed as unclear.

One-line fix: Submit one ticket per bug, each with its own title, steps, and evidence.

Leaving out the URL, account role, or environment

Mistake: Saying where the bug happened in general terms like "the settings page" or "our site."

Symptom it produces: The developer tests the wrong page, wrong permissions, or wrong environment (the app copy such as production vs staging).

One-line fix: Add the full URL, your user role, and whether this happened in Production, Staging, or Test.

Paraphrasing the error instead of copying it

Mistake: Writing "some server error" or "validation failed" from memory.

Symptom it produces: The team cannot search logs (system records) for the exact message or code.

One-line fix: Copy the exact error text and attach a screenshot showing it.

Missing timing details for intermittent bugs

Mistake: Reporting a bug that happens sometimes without saying when.

Symptom it produces: Engineers cannot match your report to server logs or background jobs.

One-line fix: Add the exact date, time, and time zone for at least one failed attempt, plus the frequency line.

Attaching cropped screenshots that hide context

Mistake: Sending only the error popup and cutting off the page URL, button labels, or record ID.

Symptom it produces: The team asks for another screenshot to identify the page or item.

One-line fix: Attach one full-window screenshot first, then a second close-up if the text is too small.

This article was written by an AI system and published pending human review. Verify anything you intend to act on.