# How to Write a Bug Report Developers Can Fix

> How to write a bug report developers can reproduce and fix: a reusable bug report template, the fields that matter, and the mistakes that stall fixes.

_Published: 2026-10-02 · CommerceCopilot_

## Why most bug reports can't be acted on

"The cart is broken" is not a bug report. It's an alarm. Someone has to respond to it, but nobody can fix it, because it doesn't say what's broken, for whom, under what conditions, or what "working" would even look like. Learning how to write a bug report that a developer can reproduce and fix on the first read is one of the fastest ways an agency team gets hours back, because every missing detail in a report becomes a round trip: a Slack message, a "can't reproduce, closing", a fix for the wrong thing.

The economics are lopsided. A complete bug report takes maybe ten minutes longer to write than a vague one, and a vague one routinely costs a developer an hour of guessing at reproduction steps. On agency work the cost doubles, because the person who saw the bug (a client, an account manager) and the person fixing it usually never talk directly. The report is the entire conversation.

This post covers the report itself: what goes in each field and why, with a template to copy. It pairs with our [Shopify development ticket templates](/blog/shopify-development-ticket-templates), which cover the bug ticket's structure alongside feature and enhancement tickets, and with [how to write development tickets a team can build from](/blog/how-to-write-development-tickets), which covers the scope and context discipline that applies to every ticket type.

## What a developer actually needs before they can fix anything

Strip away the fields and formats and a fixable bug report answers three questions:

1. **How do I see the bug myself?** A bug a developer can't reproduce is a bug they can't confidently fix. They can change code that looks suspicious, but without reproduction there's no way to confirm the fix worked.
2. **What should happen instead?** "It looks wrong" assumes the developer knows what right looks like. Often they don't, especially on a storefront they touch once a month.
3. **Where does this sit among everything else?** A bug that blocks checkout and a bug that misaligns a badge on one Android browser are both bugs. Only one should interrupt the sprint.

Mozilla's long-standing [bug writing guidelines](https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html) for Firefox call steps to reproduce the most important part of any bug report, and that holds just as well for a Shopify build as for a browser engine. Everything else in the template serves those three questions.

## How to write a bug report, field by field

### A title that identifies the bug

The pattern that works: what does the wrong thing, what it does, and when. "Cart drawer shows $0.00 line item price when a discount code is applied" can be found in a tracker search six weeks later and triaged without being opened. "Cart bug" and "URGENT pricing issue!!" cannot. If you can't write the title in this shape yet, you probably don't understand the bug well enough to report it.

### Expected versus actual

Two separate lines, always. **Expected:** the discount shows in the subtotal while line items keep their original price. **Actual:** every line item shows $0.00 once a code is applied. Splitting them forces the reporter to say what correct behavior is, and it surfaces disagreements early: a surprising number of "bugs" turn out to be the site doing exactly what the ticket asked for. If you can't fill in the expected line, the report may belong in a conversation about requirements instead, which is what [acceptance criteria](/blog/writing-acceptance-criteria-shopify-tickets) exist to settle before the build.

### Steps to reproduce, from a clean state

Numbered steps, starting from a state the developer can actually get to: an incognito window, an empty cart, a specific product URL. "Go to the cart" skips the part that matters, which is everything the reporter did before that without noticing. Cart bugs in particular are usually state bugs: they depend on what was added, in what order, with what discount or market or customer account active.

Write the steps, then run them yourself in a fresh session before filing. If the bug doesn't reproduce from your own steps, say so in the report ("happens roughly one time in five, steps below"). An intermittent bug honestly labeled is workable; "reliable" steps that fail on the developer's machine poison the whole report.

### Environment: where Shopify work gets specific

Generic bug templates ask for browser and operating system. Shopify work needs more, because the same storefront behaves differently depending on:

- **Which theme**: the live theme or an unpublished one, and if unpublished, which. Shopify's [visitor preview links](https://help.shopify.com/en/manual/online-store/themes/adding-themes) expire two days after they're created, so a report filed Friday against a preview link may be unopenable by Monday. Name the theme in the report; don't rely on the link alone.
- **Device and browser**, including the real one: a surprising share of client-reported bugs are mobile Safari only.
- **Logged-in state**: customer account or guest, since pricing, discounts, and visibility rules can differ.
- **Apps**: if the bug involves a section or widget an app injected, name the app. App-injected code is the first suspect for behavior nobody on the team recognizes.

### Severity, stated honestly

Three levels cover agency work: blocks purchase or checkout, broken but with a workaround, cosmetic. When every client-reported bug arrives marked critical, the field stops carrying information and triage falls back on whoever shouts loudest. Severity describes impact on the store, not how annoyed anyone is; a visible typo on the homepage is still cosmetic.

### Evidence: linked, not described

A screenshot for anything visual, a screen recording for anything involving interaction or timing, and the browser console if there's a visible error. Link the actual file. For hard-to-catch bugs, a recording also doubles as reproduction proof: it shows the exact clicks that triggered the problem, including the ones the reporter didn't think were relevant.

## A bug report template you can copy

```
Title: [Page/component] does [wrong behavior] when [condition]
Expected: what should happen
Actual: what happens instead
Steps to reproduce: numbered, from a clean state (fresh session, empty cart)
Environment: theme (live or unpublished, by name), device, browser,
  logged-in or guest, relevant app if known
Severity: blocks purchase / workaround exists / cosmetic
Evidence: screenshot, recording, console errors, all linked
First seen: date, and whether it worked before (what changed, if known)
```

The "first seen" line is the one most templates skip and developers quietly treasure. "Worked before Tuesday's deploy" or "started after the review app was installed" cuts the search space from the whole codebase to one diff.

## One bug per report

Mozilla's guidelines are blunt about this, and the reasoning transfers directly to agency trackers: different bugs get fixed, verified, and prioritized by different people, so a report bundling several issues means some of them never reach the right person at all. The checkout bug in a mixed report gets fixed; the cosmetic issues riding along in the same ticket get closed with it, unfixed. Five small reports triage better than one long one.

## Mistakes that stall otherwise good reports

- **Reporting the suspected cause instead of the behavior.** "The discount app is conflicting with the theme" is a theory. Report what you saw; let the developer own the diagnosis. Wrong theories anchor the investigation in the wrong place.
- **Interpreting instead of describing.** "The cart is calculating tax wrong" might actually be "the cart shows a different total than the checkout." Describe what's on the screen; keep the interpretation out of the actual line.
- **Pasting the client's message as the report.** The client's email is evidence, and worth attaching. But "customer says checkout is weird on her phone" needs translation into device, steps, and expected behavior before a developer can act on it. Relaying is not reporting.
- **Filing without reproducing.** If nobody on the team has seen the bug happen, the report should say so explicitly. There's a real difference between "reproduced on two devices" and "client reports, not yet reproduced," and triage needs to know which it's reading.

## Turning client complaints into fixable reports, at volume

One careful bug report is a discipline problem. The harder version is agency reality: bug reports arrive as Slack messages, two-line emails, and a sentence dropped in a weekly call, across six client projects at once. Someone has to translate each one into the structure above, and that someone is usually a senior person who is already the bottleneck.

This translation step is what CommerceCopilot's Business Analyst agent does with bug reports, the same way it handles briefs: it reads the client's Slack message or call transcript, drafts the structured report (expected versus actual, known environment details, severity), and flags what's missing as open questions, asking for the device or the steps instead of inventing them. A human reviews the draft before it reaches the tracker; the [brief-to-tickets walkthrough](/docs/your-first-brief-to-ticket-project) shows where that review sits. Fixed bugs then feed the other direction: a bug that reached a client is usually a state nobody tested, which is worth folding back into the [QA checklist](/blog/shopify-project-qa-checklist) so the same gap doesn't ship twice.

## FAQ

### What's the difference between severity and priority?

Severity describes impact: what the bug breaks and for whom. Priority describes order: when the team will fix it relative to everything else. They usually correlate, but not always; a cosmetic bug on the homepage of a client mid-launch can outrank a worse bug on a quiet store. The reporter sets severity, because they can observe impact. The team sets priority, because priority is a scheduling decision, not a property of the bug.

### What should I do when a bug won't reproduce?

File it anyway, labeled honestly: what was seen, where, when, and that it hasn't reproduced since. Include whatever evidence exists, especially a recording or the client's screenshot. One unreproducible sighting is low-priority by default, but three unreproducible sightings of the same behavior across two weeks are a pattern, and the pattern is only visible if each sighting got filed instead of shrugged off.

### How is a bug report different from a bug ticket?

In most teams they converge: the report is the information, the ticket is where it lives. The useful distinction is who writes each. Anyone, including a client, can produce a report in some form; turning it into a tracker-ready ticket with severity, affected template, and reproduction confirmed is the agency's job. Our [ticket templates post](/blog/shopify-development-ticket-templates) covers the tracker side of that handoff.

### Should clients be given a bug report template?

A short one, yes: what did you expect, what happened instead, what device, and a screenshot. Most clients will fill in a four-field form; none will fill in a nine-field one. The remaining fields (theme, severity, affected section) are the agency's translation work, not the client's.

---
Canonical page: https://www.commercecopilot.ai/blog/how-to-write-a-bug-report-developers-can-fix