Bug Report Template: 3 Copy-Paste Formats + Examples

TL;DR: A good bug report answers four questions: what did you do, what did you expect, what happened instead, and where (page, browser, account). Below are three copy-paste templates: a full one for QA and engineers, a five-question one for customers, and a Markdown one written for AI coding agents like Claude Code, Cursor and Codex, with acceptance criteria so the agent knows when it’s done. Each comes with a filled-in example.

What makes a bug report useful

The person fixing a bug needs to see it happen. Everything in a bug report exists to make that possible, or to help decide how soon it should be fixed. That gives you a simple test for any field: does it help someone reproduce the problem, or rank it? If not, drop it.

The fields that pass the test:

• Title: the symptom and where it happens, in one line.
• Steps to reproduce: numbered, starting from a known state.
• Expected result and actual result, written separately.
• Environment: browser and version, OS, device, app version, account type or plan.
• Frequency: every time, sometimes, once.
• Impact: how many people hit it and what it blocks.
• Evidence: error messages, console output, logs, screenshots.

Template 1: for QA and engineers

Use this in GitHub Issues, Linear, Jira or any tracker that renders Markdown.

## Summary
<!-- One line: what breaks, where. -->

## Steps to reproduce
1.
2.
3.

## Expected result

## Actual result

## Environment
- App version / commit:
- URL or screen:
- Browser + version:
- OS + device:
- Account / role / plan:
- Feature flags:

## Frequency
<!-- Always / intermittent (x of y tries) / once -->

## Severity
<!-- Blocker / major / minor / cosmetic, and why -->

## Evidence
<!-- Error text, console output, network response, logs, screenshot or recording -->

## Notes
<!-- Workaround, first seen, related issues, what you already ruled out -->

Filled-in example

## Summary
Invoice PDF download returns 500 for invoices with a discount line

## Steps to reproduce
1. Sign in as a Pro test account ([email protected])
2. Go to Billing → Invoices
3. Open invoice INV-2026-0418 (has a 20% discount line)
4. Click "Download PDF"

## Expected result
A PDF downloads with the discount shown as a negative line item.

## Actual result
Toast: "Something went wrong." Network tab shows
GET /api/invoices/INV-2026-0418/pdf → 500.

## Environment
- App version / commit: web 4.12.0 (a1b9c3e)
- URL or screen: /billing/invoices/INV-2026-0418
- Browser + version: Chrome 129
- OS + device: macOS 15, MacBook Air
- Account / role / plan: Pro, owner
- Feature flags: new-pdf-renderer = on

## Frequency
Always, for any invoice with a discount line. Invoices without discounts work.

## Severity
Major. Customers can't get invoices for accounting; support is sending them by hand.

## Evidence
Server log:
TypeError: Cannot read properties of undefined (reading 'amount')
    at renderLineItem (pdf/render.ts:88)

## Notes
Started after new-pdf-renderer was enabled on Sept 22. Turning the flag off fixes it.

Notice what makes this one fast to fix: the reporter found the pattern (only discounted invoices), attached the server error, and noted the flag that correlates with the start date. None of that takes long once you’re in the habit.

Template 2: for end users and customers

Customers won’t fill in twelve fields, and they shouldn’t have to. Ask five questions in plain language. Put this in a support form, a help center page or an email reply.

Sorry you ran into this. To help us fix it quickly:

1. What were you trying to do?
2. What happened instead? (An error message word for word is great.)
3. Where did it happen? (Page link or screen name.)
4. Does it happen every time?
5. Which browser or device are you using? (For example "Chrome on Windows" or "iPhone app".)

A screenshot helps a lot if you can grab one.

Filled-in example

1. What were you trying to do?
   Export my contacts to a spreadsheet.

2. What happened instead?
   I click Export and nothing happens. No error, no file.

3. Where did it happen?
   The Contacts page.

4. Does it happen every time?
   Yes, tried 4 times today. It worked last week.

5. Which browser or device?
   Safari on my Mac.

This is a decent report from a non-technical user. It’s still missing the Safari version, whether other browsers work, and the account it happened on. You can collect those without asking the user at all, which is covered further down.

Template 3: for AI coding agents

When the reader is Claude Code, Cursor or Codex, a few things change. The agent can’t ask a teammate what you meant, it will read every word literally, and it needs to know when to stop. So this format adds:

• Scope hints: likely files or modules, so the agent doesn’t search the whole repo.
• Acceptance criteria: checkable statements the fix must satisfy.
• Verification: how to prove it works (a test to add, a command to run).
• Constraints: what not to touch.
• User evidence: quotes and counts, which help the agent weigh edge cases.

Save it as a Markdown file in the repo (for example bugs/1234.md) or paste it into the prompt.

# Bug: <symptom> on <page/feature>

## Context
- Reports: <n> users, last reported <date>
- Plans affected: <free / pro / all>
- Frequency: <always / intermittent / specific condition>

## Steps to reproduce
1.
2.
3.

## Expected

## Actual

## Environment
- URL / route:
- Browser(s) + version:
- OS / device:
- App version or commit:

## Evidence
<!-- Error messages, stack traces, console or server logs, failing request/response -->

## User quotes
> "..."

## Likely location
<!-- Files, components or endpoints to start with. Say "unknown" if unknown. -->

## Acceptance criteria
- [ ]
- [ ]

## Verification
<!-- Test to add or update, command to run, manual check -->

## Constraints
<!-- What must not change: public API, DB schema, other browsers, etc. -->

Filled-in example

# Bug: Contact export does nothing in Safari on /app/contacts

## Context
- Reports: 7 users, last reported 2026-09-26
- Plans affected: all
- Frequency: always in Safari; Chrome and Firefox work

## Steps to reproduce
1. Open /app/contacts in Safari 18 (macOS or iOS)
2. Click "Export CSV"

## Expected
A contacts.csv file downloads.

## Actual
Nothing happens. No download, no error shown to the user.

## Environment
- URL / route: /app/contacts
- Browser(s) + version: Safari 18 on macOS 15 and iOS 18
- OS / device: Mac and iPhone
- App version or commit: main @ 7f3e2d1

## Evidence
Safari console: no errors. The click handler runs and creates a Blob URL,
but the download never starts.

## User quotes
> "I click Export and nothing happens."
> "Export worked last week, now it's dead on my iPhone."

## Likely location
- src/features/contacts/ExportButton.tsx
- src/lib/download.ts (downloadBlob helper)

## Acceptance criteria
- [ ] Export downloads a .csv in Safari 17+ on macOS and iOS
- [ ] Chrome and Firefox behaviour is unchanged
- [ ] If the export fails, the user sees an error message instead of nothing

## Verification
- Add a unit test for downloadBlob covering the anchor-click path
- Run `pnpm test src/lib/download`
- Manually check export in Safari with the Playwright WebKit browser

## Constraints
- Don't change the CSV format or the /api/contacts/export endpoint
- Keep downloadBlob's signature; other features use it

Two notes on writing these. First, acceptance criteria should be testable facts, not intentions: “downloads a .csv in Safari 17+” rather than “export works better”. Second, include the error-handling criterion even if nobody asked for it. Silent failures are how this kind of bug reaches users in the first place.

A prompt to go with the file can be short:

Read bugs/1234.md. Reproduce the bug, fix it, meet every acceptance criterion, and run the verification steps. Don’t change anything listed under Constraints.

Common mistakes in bug reports

Combining expected and actual. “Export is broken” hides both. Write what should happen and what did happen as two separate lines.

Steps that start in the middle. “Click Save” on which page, signed in as whom, with what data? Start from a state anyone can recreate.

Paraphrasing error messages. “Some kind of permissions error” can’t be searched. Copy the exact text.

Missing the environment. Browser and version cause a large share of front-end bugs. So do plan and role, since different accounts see different code paths.

Several bugs in one report. Each gets fixed, tested and closed separately. Split them.

No frequency. “Always” and “once in twenty tries” lead to very different debugging.

Leaving out impact. One user on a free trial and forty paying customers are not the same priority. Say how many and who.

For agent reports, vague acceptance criteria. An agent will stop as soon as it believes the task is done. If “done” isn’t defined, it defines it for you.

How to get good reports from non-technical users

You can’t train customers to write bug reports, and a long form mostly gets abandoned. What works better:

Ask one or two follow-up questions, not a form. Let people describe the problem in their own words first, then ask for the single most useful missing detail. “Which browser are you using?” or “What did you click right before that?” gets answered. A twelve-field form doesn’t.

Capture context automatically. The page URL, browser, OS and device are available to your site without asking. If the user is signed in, so are their account id and plan. Attach all of it to the report so the user only has to explain what went wrong.

Group duplicates. Seven vague reports of the same problem are more useful together than apart: between them you usually get the browser, the steps and the exact message. Grouping also gives you the frequency count for free.

Tell people when it’s fixed. Users who hear back report again next time, and their next report is usually better.

How Feedbot collects bug reports

Feedbot is an AI chat widget for your site that answers questions from your docs, helps with sales questions, and also listens for bugs, complaints and ideas in the same conversation. Instead of a form, the user types what’s wrong. The bot asks a follow-up for the missing detail, like the browser or the steps, and then carries on helping.

Behind the scenes, Feedbot groups similar reports across conversations into product issues. Each issue includes:

• a short description and a category (bug, UX, missing feature, idea);
• how many times it was reported and when it was last reported;
• user quotes;
• affected pages and browsers;
• suggested acceptance criteria;
• links to the source conversations.

If you identify signed-in users (Starter and higher), you can pass metadata like the user’s plan, so reports come with account context the user never had to type. The setMetadata command in the JavaScript API attaches extra context to a conversation.

From there, the issues go to your coding agent in the same shape as Template 3. On Pro and Business, the agent can read them through the MCP server, npx feedbot pull writes one Markdown file per issue to .feedbot/issues/, or you can copy an agent-ready report from the Insights page. Issues can also be exported to GitHub Issues or Linear. When an issue is marked fixed, the bot stops working around the problem, and if you enable it, tells the users who reported it.

See how the feedback widget works, or follow the setup guide in Send user feedback to your coding agent via MCP.

FAQ

What should a bug report include?

A one-line summary, numbered steps to reproduce, the expected and actual results, the environment (browser, OS, device, app version, account type), how often it happens, how many users it affects, and any error messages or logs. For a coding agent, add acceptance criteria and a way to verify the fix.

How do I write a bug report that a developer can act on?

Start from a state anyone can recreate, write steps a stranger could follow, copy error messages exactly, and keep one bug per report. Then reread it and ask: could someone who has never seen this bug reproduce it from what I wrote?

What’s the difference between a bug report for a developer and one for an AI coding agent?

The core is the same. The agent version adds a likely location in the code, testable acceptance criteria, verification steps and constraints, because an agent can’t ask clarifying questions and will stop as soon as it thinks the task is done.

Should customers use the same bug report template as QA?

No. Give customers four or five plain questions and collect the technical details (page, browser, account) automatically. Converting their answers into the engineering format is your team’s job, or your tooling’s.

Is there a bug report example I can copy?

Yes. Each of the three templates above has a filled-in example you can adapt: an invoice PDF error for QA, a contact export problem described by a customer, and the same export bug rewritten for a coding agent.