Quick answer
Every bug report needs: a searchable title ([Area]: [what goes wrong] when [trigger] ([environment])), environment, numbered steps to reproduce, expected vs actual result, how often it happens, severity, and evidence (a short screen recording beats a paragraph). Copy the template below.
The template (Markdown)
Paste it into any tracker that understands Markdown. The HTML comments are hints for the reporter and don't show in the rendered issue.
### Summary (required)
<!-- One sentence: what breaks and who it affects. -->
### Environment (required)
<!-- Version or build, URL or screen, browser or device + OS, account/plan, feature flags. -->
Build:
URL / screen:
Browser or device + OS:
Account / plan:
Flags:
### Steps to reproduce (required)
<!-- Start from a known state. One action per step. -->
1. Logged in as
2.
3.
### Expected result (required)
<!-- What should happen. Link the spec or last working version if you can. -->
### Actual result (required)
<!-- What happens instead. Paste the exact error text. -->
### How often does it happen? (required)
<!-- Tick one -->
- [ ] Always (every try)
- [ ] Often (more than half of tries)
- [ ] Sometimes (less than half)
- [ ] Once so far
### Severity (see the severity guide) (required)
<!-- Triage may change it. -->
<!-- Tick one -->
- [ ] S1 Critical: data lost/exposed or core flow blocked, no workaround
- [ ] S2 Major: core feature wrong or failing for a group
- [ ] S3 Minor: works with an easy workaround
- [ ] S4 Cosmetic: looks or reads wrong only
- [ ] Not sure (triage will set it)
### Evidence
<!-- Drag in a screen recording or screenshot. Add console errors, request IDs or log links. -->
### Console or log output
<!-- Paste text, not screenshots of text. Remove secrets and personal data. -->
```shell
```
### Workaround
<!-- What users can do meanwhile, or "none known". -->
### Before you submit (required)
- [ ] I searched existing issues and this is not a duplicate
- [ ] I removed passwords, tokens and personal data from attachmentsThe title formula
[Area]: [what goes wrong] when [trigger] ([environment])
| Instead of | Write |
|---|---|
| Checkout broken | Checkout: card form clears after applying a coupon (Safari 18, prod) |
| Login issue!! | Login: "Invalid token" after password reset link is opened twice (all browsers) |
| Export bug | CSV export: rows after 10,000 are missing (Team plan, prod) |
| App is slow | Dashboard: first load takes 9 s with 50+ projects (Chrome, staging) |
Before and after
Before: "Checkout doesn't work."
After: "Checkout: card form clears after applying coupon SAVE10 (Safari 18.1, prod). Steps: 1) add any item, 2) enter card, 3) apply SAVE10. Expected: card stays filled. Actual: card fields empty, no error. 5 of 5 tries. Chrome works. Video attached."
Before: "Sometimes the app logs me out."
After: "Session: logged out after ~30 min while active in the editor (Chrome 141, prod). Happened 3 times today at 10:02, 10:41, 11:15 IST. Console shows 401 on /api/session/refresh. Request IDs in thread. Started after release 4.12."
What each field is for
| Field | What to write |
|---|---|
| Title | Area, what goes wrong, the trigger, the environment. Searchable in six months. |
| Summary | One or two sentences. What breaks and who it affects. |
| Environment | Build or version, URL or screen, browser or device and OS, account or plan, feature flags. |
| Steps to reproduce | Numbered, starting from a known state ("logged in as a Team admin"). One action per step. |
| Expected result | What should happen, ideally with a link to the spec, docs or the last working version. |
| Actual result | What happens instead, with the exact error text. |
| Frequency | Always, sometimes (x of y tries), or once. Intermittent bugs need the count. |
| Evidence | Screen recording, screenshot, console errors, network request (HAR), request ID, log link. |
| Impact and reach | Who is affected and how many. Revenue, data or support impact if known. |
| Regression? | Did it work before? Last known good version or date. |
| Workaround | What users can do meanwhile, or "none known". |
| Severity | Using the guide. Priority is set in triage. |
Using a spreadsheet instead (Excel / Google Sheets)
If your team tracks bugs in a sheet, use the same fields as columns. Paste this line into cell A1, then use Data → Split text to columns (Sheets) or Data → Text to Columns (Excel) with comma as the separator:
ID,Title,Summary,Environment,Steps to reproduce,Expected result,Actual result,Frequency,Severity,Priority,Evidence link,Status,Owner,Reported onRecord the video part
A 60-second recording of the bug happening removes most back-and-forth. Attach it next to the written steps, not instead of them. Bobbin is a free Chrome extension that records your screen, a window or a tab with your microphone and an optional webcam bubble. No account, no watermark, no time limit, and nothing is uploaded: the file stays on your computer.
- Click the Bobbin icon in Chrome's toolbar and choose Record screen, window or tab.
- Pick your microphone and turn on the camera if you want the webcam bubble.
- Press Start recording, choose what to share in Chrome's picker, and wait for the 3-second countdown.
- Pause with Alt+Shift+P, stop with Alt+Shift+S, then press Download to save the file.
To keep other tabs and notifications out of it, share just the Chrome tab (the webcam bubble appears only in screen and window recordings). Bobbin saves MP4 where your browser supports it (Chrome 126 or newer), WebM otherwise, and tells you which it used.
File size: our 60-minute 1080p test came to about 246 MB (roughly 4 MB a minute) on a simple synthetic screen; busy real screens can be larger, so a 1–2 minute clip is usually small enough to attach.
Script for it: how to record a bug report video.
From The Bug Report & QA Kit
This is 1 of 10 templates. The full kit: 10 bug templates for GitHub, Jira, Linear and Markdown, 9 release checklists (126 checks), the severity guide, 8 bug-video scripts and trackers.
See the QA kit ($15, one-time) PDF + ZIP · 7-day refund · more free samples on the page