Purpose
A bug report is a fix request that lets a defect be reproduced and fixed on the first try, with no "how do I repro?". A good one saves hours: exact steps, expected vs actual, and evidence.
Formula: Steps → Expected → Actual → Severity/Priority → Environment → Attachment (log/screen/video).
Template
# <short symptom>
## Steps — 1) … 2) … 3) …
## Expected — what should happen. ## Actual — what happened.
## Severity (blocker|critical|major|minor) / Priority (P1|P2|P3)
## Environment — OS/browser/app version/device. ## Evidence — log/screenshot/recording. ## Frequency.
Example 1 — crash
# Clipping fails on videos over 10 minutes
## Steps — open Shorts; upload a 12:30 video; click Clip.
## Expected — clips into 9:16, a list appears. ## Actual — spinner ~30s, then "Something went wrong", no clips.
## Severity: critical · Priority: P1 ## Env: Windows 11 · Chrome 125 · web 2.3.1 ## Evidence: console RangeError (screenshot) ## Frequency: always on >10 min.
Example 2 — visual/UX
# "Save" button cut off on iPhone SE
## Steps — open a tool card on iPhone SE; open the "Add note" modal; look at the bottom button.
## Expected — "Save" fully visible & tappable. ## Actual — half off the bottom edge, untappable.
## Severity: major · Priority: P2 ## Env: iOS 17 · Safari · iPhone SE (375px) · web 2.3.1 ## Evidence: screenshot ## Frequency: always on ≤375px.
Quality checklist
- Title is a short symptom.
- Steps reproducible by anyone.
- Expected vs actual separated.
- Severity ≠ Priority, both set.
- Environment present.
- Evidence & frequency present.
Common mistakes
"Doesn't work"; mixing expected/actual; severity = priority; no environment; no evidence.