A bug report isn’t a complaint. It’s a handoff. The goal is to let someone else reproduce the problem, understand the impact, and fix it without guesswork.
If your reports are vague, you get vague outcomes: long Slack threads, “can’t reproduce,” and fixes that don’t actually fix. A good template saves time for everyone, especially when your product was built quickly and behavior can vary across devices, sessions, and environments.
Bug report template: what to include (and why it works)
A good report does two things at once:
- It tells the story (what you were trying to do, what went wrong, how bad it is).
- It provides evidence (repro steps, expected vs actual, screenshots, environment details, logs).
Reproduction steps: how to make “works on my machine” unlikely
Repro steps are the heart of a useful report. They turn “it’s broken” into a test a developer can run.
Write steps like you’re handing your laptop to someone who’s never seen the product:
- Start from a known state (logged out vs logged in, empty cart vs full cart).
- Include the exact path (menu clicks, URLs, button labels).
- Include inputs that might matter (email format, file size, plan tier).
- Stop as soon as the bug appears.
If it’s intermittent, say so and add a repro rate: “Happens ~1 in 5 attempts.”
Expected vs actual: align on the behavior you want
Keep this simple:
- Expected: what should happen (tied to the user goal).
- Actual: what happened instead (with the exact message or symptom).
If you’re unsure what “expected” is, write what a reasonable user would expect. That often reveals a product ambiguity worth fixing too.
Screenshots and recordings: what to capture (and what to blur)
Aim to include:
- one screenshot right before the bug,
- one screenshot of the failure state,
- a short recording (10–30 seconds) if it’s a flow issue.
Blur sensitive data. Never include tokens, passwords, or private keys.
Environment details: the small facts that change everything
Good environment details usually include:
- device + OS (e.g., “iPhone 15, iOS 17”)
- browser + version (e.g., “Safari 17”)
- app environment (prod/staging) + build/version if you have it
- account context (plan tier, role/permissions, workspace/tenant)
- timestamps (with timezone)
Logs and error messages: what to paste, what to avoid
If you can, include:
- exact error text (not paraphrased),
- status codes (401/403/500) and endpoint names,
- request IDs / correlation IDs.
Avoid pasting secrets: API keys, session tokens, or private webhook payloads.
Severity and impact: choosing priority without drama
Severity isn’t “how annoyed I am.” It’s user impact and business risk. A simple scale:
- S0: outage, data loss, security risk
- S1: major core flow broken, no workaround
- S2: moderate impact, workaround exists
- S3: minor or cosmetic
If you’re unsure, state impact plainly: “Blocks new signups,” “Prevents upgrades,” “Only admins affected,” “Only on iOS.”
Copy/paste bug report template (Markdown)
Title: Feature + symptom (e.g., “Login redirect loop on iOS Safari”)
Summary: One paragraph: what happened, where, who it affects
Severity: S0 / S1 / S2 / S3 (and why)
Reproduction steps:
Expected vs actual:
- Expected:
- Actual:
Screenshots / recording:
- Link(s) or attachment(s):
- Notes (what to look at):
Environment:
- App: prod/staging + version/build if known
- Device + OS:
- Browser + version:
- Account context (role/plan/workspace):
- Timestamp(s) + timezone:
Logs / errors:
- Console error(s):
- Network error(s): endpoint + status code
- Request ID (if available):
Impact: Who is blocked? Any revenue risk?
Workaround: If any; otherwise “none found”
Recent changes: “Started after deploy X” / “after enabling integration Y”
Pre-send checklist (60 seconds)
- Do the repro steps start from a clear state?
- Did you include expected vs actual in plain language?
- Did you attach a screenshot or short recording if it’s UI-related?
- Did you include environment details and timestamps?
- Did you paste exact error messages (and redact secrets)?
- Did you pick severity based on impact and workaround?
Bug report mistakes that waste hours
Most bad reports fail in predictable ways:
- They describe a feeling instead of a behavior (“it’s broken” without steps).
- They include too many steps, so the team can’t tell what matters.
- They skip expected vs actual, so everyone debates what “correct” is.
- They omit environment and time, so engineers chase the wrong logs.
- They paste partial errors (“some 500”) instead of the exact message and endpoint.
A useful trick: if you can’t reproduce it twice in a row from your own steps, the report isn’t done yet. Tighten the steps until you can.
Examples: auth loop and missing webhooks
Flaky auth loop (intermittent). Include a repro rate and device/browser details. A 15-second recording showing the URL bouncing between /auth/callback and /login is more useful than a paragraph of frustration.
Webhook missing (integration). Don’t say “Stripe webhook didn’t fire.” Provide the invoice/event ID, the time window, and what state you expected in your app (upgrade within 30 seconds, email sent, access granted).
Data looks wrong after a deploy (state corruption). If a report says “the dashboard numbers are off,” include one affected record ID, what the numbers were yesterday, and what changed. If you have it, include the deploy timestamp. Those details help engineers trace what code path wrote bad data.
After you file it: how to speed up the fix
Two small habits make fixes ship faster:
- Reply quickly to follow-up questions (it’s usually one missing detail).
- Retest the fix in the same environment you reported (same browser/device if relevant).
If you can add one more thing to your workflow, add a “customer impact” sentence to the ticket. “Blocks new users from onboarding” or “affects upgrades” changes priority more than any screenshot.
Spin by Fryga (brief): when bug volume blocks progress
If your app was built fast and bug volume is now blocking progress, the best investment is often making failures debuggable: better logging, clearer states, and safer releases. That’s part of the stabilization work Spin by Fryga does when teams need fixes without a rewrite.