A good bug report lets someone who has never seen the problem make it happen on their own machine. This template covers the fields every bug report template has (steps, expected, actual, environment, severity) and adds the ones most leave out: how often it reproduces, whether it is a regression, and the workaround.
Updated 2026-10-27
Copy and adapt
The template
Bug reportTemplate
[Area] [What breaks] on [platform or condition]
Reported by: [name], {{date}}
Severity: [S1 critical / S2 major / S3 minor / S4 cosmetic]
Priority: [P1 to P4, set by the triager]
Status: [New / Confirmed / In progress / Fixed in version]
Environment
App version and build: [version (build)]
OS and device: [OS version, device model]
Browser: [name and version, if web]
Account: [account or workspace ID, plan, feature flags]
Where: [URL or screen name]
Steps to reproduce
[Start from a known state: logged in as, on page]
[Action]
[Action]
Expected result
[What should happen]
Actual result
[What happens instead. Paste exact error text and codes]
Reproducibility
[Always / N of M attempts / once, could not repeat]
Regression
[Worked in version X, broken since version Y / not known]
Impact
[Who is affected, how many, money or data at risk]
Add any 2 items to the cart and go to checkout as a guest.
Tap Apple Pay, then close the Apple Pay sheet without paying.
Choose Card and fill in the test card details.
Tap Pay.
Expected result
Card payment is submitted and the confirmation page loads.
Actual result
The Pay button shows a spinner for half a second, then returns to normal. No request is sent (network tab shows nothing). Console: Unhandled Promise Rejection: AbortError: The operation was aborted.
Reproducibility
10 of 10 on iOS Safari. 0 of 10 on Chrome for iOS and desktop Safari.
Regression
Worked in 2026.10.2. Broken since 2026.10.3, which updated the payment SDK.
Impact
iOS Safari is 38 percent of checkout traffic. Any customer who opens and closes Apple Pay cannot pay by card without reloading.
Workaround
Reload the page after closing Apple Pay. Cart is kept.
Attachments
Screen recording (34 s), Safari console export
Related
Payment SDK upgrade PR #2214
2.Mobile app crash with build number and log
When it fits: Use this when the app crashes, the reporter is an engineer or a tester with access to logs, and the crash only happens for users with a particular kind of data.
Mobile app crash with build number and logExample 2
[Photos] App crashes when opening an album with more than 1,000 photos on iOS
Reported by: Daniel Osei, 2026-10-22
Severity: S1 critical
Priority: P1
Status: In progress (assigned to Mei)
Environment
iOS app 4.18.0 (build 6120), TestFlight
iPhone 13 mini, iOS 26.0.1
Album "Wedding 2025", 1,412 photos
Steps to reproduce
Sign in with an account that has an album over 1,000 photos (seed account qa-large-albums).
Open Albums.
Tap the large album.
Expected result
Album grid loads and scrolls.
Actual result
App closes after about 2 seconds. Crash log top frame: EXC_RESOURCE RESOURCE_TYPE_MEMORY (limit=2098 MB) in ThumbnailCache.prefetch(_:).
Reproducibility
5 of 5 with 1,412 photos. 0 of 5 with an 800-photo album.
Regression
Not in 4.17.2. Thumbnail prefetching was added in 4.18.0.
Impact
Crash reports show 2,300 affected users in the TestFlight group; about 9 percent of active users have an album this large.
Workaround
None in the app. Users can view the album on the web.
Attachments
Full crash log, memory graph from Xcode, seed account details in the QA vault
3.Intermittent bug reported honestly
When it fits: Use this when you cannot make the bug happen every time, you are tempted to wait until you can, and a report that says what you do and do not know is more useful than silence.
Intermittent bug reported honestlyExample 3
[Notifications] Some customers get the order-shipped email twice
Reported by: Fatima Zahra (support), 2026-10-19
Severity: S3 minor
Priority: P2
Status: New
Environment
Production, transactional email service
Seen on orders from 2026-10-14 onwards
Steps to reproduce
Not reproduced on demand. What we have:
Order ships (warehouse marks it shipped).
Customer receives "Your order is on its way" twice, 1 to 3 minutes apart.
Expected result
One email per shipment.
Actual result
Two identical emails, same tracking number, different message IDs.
Reproducibility
11 customer reports out of roughly 4,200 shipments since Oct 14. Our own test orders: 0 of 6.
Regression
First report Oct 14. The warehouse integration was redeployed on Oct 13.
Impact
Mostly confusion, but 3 customers thought they had been charged twice and opened disputes.
Workaround
Support macro "duplicate shipping email" sent to affected customers.
Attachments
List of 11 order IDs with both message IDs and timestamps
What I do not know
Whether the warehouse sends the shipped event twice, or our system sends one event twice. The message IDs suggest two separate sends.
4.Data-correctness regression with a workaround
When it fits: Use this when nothing crashes and nothing looks broken, but numbers are wrong, and the people affected will not notice until they reconcile against another system.
Data-correctness regression with a workaroundExample 4
[Exports] CSV export rounds currency amounts to whole numbers
Open Reports, then Transactions, filter to October 2026.
Click Export as CSV.
Open the file and compare the Amount column with the table on screen.
Expected result
Amounts with two decimals, matching the screen (e.g. 1,249.95).
Actual result
Amounts rounded to whole numbers (1250). The October total in the file is off by 37.40 EUR against the screen.
Reproducibility
Always, for every workspace we tried (4 of 4), any currency.
Regression
Correct in 5.7.x. Broken since 5.8.0, which changed the export number formatting.
Impact
Any workspace reconciling from the CSV since 5.8.0 (released 2026-10-06) has wrong totals. Finance teams may already have closed September books with this file.
Workaround
Export as XLSX instead; amounts are correct there. Or use the API endpoint for transactions.
Related
Should be announced to affected workspaces once fixed. Ask customer success for the list of workspaces that exported CSV since Oct 6.
5.Bug reported by a non-engineer
When it fits: Use this when the reporter works in support or operations, does not know the system internals, and the goal is a report an engineer can act on without a follow-up call.
Bug reported by a non-engineerExample 5
[Admin tool] Merge accounts fails with "Something went wrong" for one customer
Reported by: Tamsin Moore (customer support), 2026-10-27
Severity: S3 minor
Priority: P3
Status: New
Environment
Internal admin tool, Chrome on my work laptop
Customer accounts 55120 (old email) and 61873 (new email)
Steps to reproduce
Open account 61873 in the admin tool.
Click Merge accounts and enter 55120.
Click Confirm merge.
Expected result
The two accounts become one, keeping the order history from both. This works for other customers; I merged 3 others today.
Actual result
Red banner: "Something went wrong. Reference: req_8f3a21c9". Nothing changes on either account.
Reproducibility
3 of 3 tries for this customer, 10 minutes apart.
Impact
One customer, who cannot see orders placed under the old email. They need an invoice from the old account for an expense claim by Friday.
Workaround
I sent the invoice from the old account by email. The customer still wants one login.
Attachments
Screenshot of the error banner with the reference number
What makes a bug report get fixed
Every bug report template on the first page of search results has the same core: title, steps, expected, actual, environment, severity, attachments. Those fields are necessary. They are not what decides whether a report gets fixed this week or bounces back with "cannot reproduce". Three fields do that, and most templates leave them out:
Reproducibility. "3 of 10 attempts" tells the developer to keep trying. A missing value tells them to try once and close the ticket.
Regression. "Worked in 5.7, broken in 5.8" narrows the search to one release. It is often the fastest route to a fix, and the reporter is usually the only person who knows.
Workaround. It changes priority. A severe bug with a good workaround can wait for the next release; a minor bug with no workaround and a customer deadline might not.
How to write the steps
Start from a known state: who is logged in, which page, what data. Then one action per line, with the exact button names in bold. Stop at the first step where the result differs from what you expected. If the bug needs special data (an album over 1,000 photos, a workspace in EUR), say so in step one or name a seed account. Then do one thing that saves everyone time: follow your own steps once more, from the start, before you submit.
Severity levels
Define them once for the team and link the definitions from the template, so "major" means the same thing to everyone.
S1 critical. Crash, data loss, security issue, or a core flow (sign-in, checkout) blocked with no workaround.
S2 major. A core flow broken for some users, or wrong data, with a workaround.
S3 minor. A secondary feature broken or confusing; most users unaffected.
S4 cosmetic. Visual or copy issue with no functional effect.
A feature request template
When the software works as designed and someone wants it to work differently, use a different form. It asks about the problem rather than the steps, so the request does not get triaged as a defect.
**Title:** [Area] [What the user wants to do]**Requested by:** [name, role, customer or internal]**Problem:** [What they are trying to do and what stops them today]**How often:** [How many users or requests, with a source]**Current workaround:** [What they do instead, and what it costs them]**Suggested solution (optional):** [Their idea, kept separate from the problem]**Related:** [Other requests for the same thing]
Keep the problem and the suggested solution in separate fields. Five requests for five different solutions are often one problem, and the problem is what goes on the roadmap. If a request turns into planned work, it becomes a user story with acceptance criteria.
Common mistakes
One report, three bugs. Each gets fixed on a different day. Split them so each can be closed.
Screenshots without text. Paste the error message as text too. Screenshots of logs cannot be searched in most trackers.
"It doesn't work". Say what you expected and what happened. "Doesn't work" might be a crash, a wrong number or a slow page.
Missing version. A bug in an old build may already be fixed. Without the version, nobody can tell.
Closing as "cannot reproduce" without asking. Ask for the one missing detail first. The intermittent bugs are usually the expensive ones.
If a bug caused an outage or reached many customers, the report is the start of the record, not the end. Follow it with a post-mortem once it is fixed.
Customization tips
Write the title as area, what breaks, where
"[Checkout] Pay button does nothing after closing Apple Pay on iOS Safari" can be triaged from the list view. "Checkout broken" has to be opened, read and probably asked about.
Say how often, in numbers
"Sometimes" sends the bug to the bottom of the queue. "11 of about 4,200 shipments" or "3 of 10 attempts" tells the developer how hard to look and how to know a fix worked.
Always fill in the regression line
"Worked in 5.7, broken in 5.8" cuts the search from the whole codebase to one release. If you do not know, write "not known" so nobody assumes it was checked.
Keep severity and priority apart
Severity is how bad the bug is for the user, and the reporter can judge it. Priority is when it gets fixed, and the triager sets it. A typo on the pricing page is low severity and can still be P1.
Feature requests need a different shape
If the software does what it was built to do and the user wants something else, it is a feature request, not a bug. Use the short feature request template further down this page so it does not get triaged as a defect.
Trim it for public issue trackers
For bug reports from outside contributors, four required fields (what happened, steps, version, logs) get more complete reports than twelve. Our GitHub issue template guide covers which fields to make required.
In the app
How to do this in Scribelet
1
Open Desk Settings, then Templates, tap Add Template and paste the template above with #bug as a default tag. Keep {{date}} on the Reported by line.
2
Attach the screenshot or the PDF of the error page to the note. Scribelet extracts the text from it, so the error message and reference number are searchable later.
3
Found a bug away from your desk? Record a voice note (Pro). Scribelet transcribes it and structures it into a note with headings you can tidy into this template.
4
Link the component with [[Exports]] so its backlinks panel lists every bug, decision and release note that touched it, which helps spot a regression pattern.
5
Add a follow-up like - [ ] Retest on 5.8.2 @due(2026-11-03). It stays in the Tasks view until you tick it.
6
Connect Scribelet's MCP server to Claude Code or Cursor and an agent can read the bug report, including steps and expected result, while it investigates the fix.
Templates, template variables and AI generation are documented in Note templates.
Frequently asked questions
What should a bug report include?+
A specific title, the environment and version, numbered steps to reproduce, the expected and the actual result, and attachments such as a screenshot or log. The template above adds reproducibility, regression, impact and workaround, which are what a triager needs to set priority.
What is the difference between severity and priority?+
Severity measures the impact on users: a crash or data loss is S1, a cosmetic issue is S4. Priority measures how soon it should be fixed, and depends on business context as well as severity. The reporter proposes severity; the triager or product owner sets priority.
What should I do if I cannot reproduce the bug?+
Report it anyway, and say so. Write what you saw, when, on which account, how many times you tried, and what you do not know. The third example above is a bug that could not be reproduced on demand and is still actionable because of the order IDs and timestamps.
What is the difference between a bug report and a feature request?+
A bug report says the software does not do what it was meant to do. A feature request says it should do something it was never meant to do. They need different fields: a bug needs steps and versions, a feature request needs the problem and who has it. Our GitHub issue template guide shows both as issue forms.
Can I use this bug report template in Jira, GitHub or Linear?+
Yes. It is plain Markdown, so it pastes into a Jira description, a GitHub issue or a Linear ticket. In GitHub you can save it as .github/ISSUE_TEMPLATE/bug_report.md so it appears whenever someone opens an issue.
Bug reports you can find again when it comes back
Save this bug report template in Scribelet, attach the screenshot so the error text is searchable, and link each bug to the component it broke. When it reappears in three releases, ask your notes when it was last fixed. Encrypted, free to start.