Bug Report Craft

From “need more info” to “merged in 24 h”

Finding a bug is a third of the work. Writing it up so that a stranger can reproduce it, prioritise it, and fix it without asking you three follow-up questions — that's the rest. Six elements, with bad-vs-good side-by-side, that turn tickets into handoffs.

The compounding cost: a vague bug report costs one round-trip (~24h) to clarify. Ten vague reports in a sprint burn a developer-week that should have been spent fixing. Good reports are a force multiplier for the whole team.

1. Title — one-line, searchable, unambiguous

The title is the ticket's primary key in tribal memory. Future engineers search it when a regression appears. Vague titles are buried within a week.

Bad

Title: "Bug"
Title: "Doesn't work"
Title: "Login is broken"
Title: "Checkout issue on Safari ???"
Title: "URGENT FIX ASAP!!!"

Good

Title: "[checkout] Pay button submits twice when network >2s latency"
Title: "[auth] Session cookie not rotated after login — fixation possible"
Title: "[products] Catalog sort by price reverses every 2nd click"
Title: "[api/v1/users] GET /users/:id returns 200 with null body on unknown id"

Rule of thumb: Format: [area] observable-behaviour under precondition. No adjectives, no punctuation drama, no ALL CAPS. If you can grep for it in 6 months and find it, the title works.

2. Reproduction steps — deterministic, minimal, numbered

A bug that can't be reproduced gets closed as CANNOT REPRODUCE within a week. Your job is to hand the developer a recipe, not a witness statement.

Bad

Reproduction:
"Sometimes when you do stuff on the cart page it breaks"
"I clicked around and got an error"
"It happened yesterday, I don't remember what I did"
"Login flow is buggy, please check"

Good

Reproduction:
1. Open Chrome 127, Incognito, size 1440×900
2. Navigate to https://stg.qa-practice.dev/products
3. Add 2× "Wireless Mouse" to cart
4. Click "Checkout"
5. In shipping form, fill all fields (sample data below)
6. Click "Continue to payment"
7. Observe: form resets AND cart is empty

Sample data:
{ email: "t@t.dev", name: "Test User", phone: "+1 555 1234" }

Frequency: 3/3 attempts. Persists across browser restart.

Rule of thumb: Numbered steps anyone can replay. Include env (browser, viewport, incognito/not), sample data, and frequency. If the steps work once but not every time, say that loudly — intermittent bugs need different handling.

3. Expected vs Actual — the gap is the bug

Developers read 'expected' to understand the contract, 'actual' to understand the failure mode, and the delta to decide if it's a bug vs a feature.

Bad

"The button doesn't work"
"Wrong behaviour"
"Should be different"
"Not what I wanted"

Good

Expected: After clicking "Place order", the cart should clear,
the user should see a confirmation page with order number,
and an email should arrive within 60s.

Actual: Cart remains full. No confirmation page renders.
Order appears in user's /orders history (so the POST succeeded)
but no email is sent. User tries again and gets a duplicate order.

Specification source: /docs/checkout-flow.md#success-path
or link to design mockup / Jira spec / etc.

Rule of thumb: Cite the spec source if possible ('per docs/...' or 'per design at Figma url'). Without a cited expectation, 'bug' is just 'I disagree with the product'. With a cited expectation, it's a contract violation.

4. Evidence — screenshots, network, console, logs

Text descriptions compress loss. A 10-second screen recording removes ambiguity a 200-word description creates. Logs prove what your eyes didn't see.

Bad

Evidence: (none)
Evidence: "See screenshot" (no screenshot attached)
Evidence: Broken.png — a blurry photo of a monitor taken with a phone
Evidence: A 47-minute unedited Zoom recording

Good

Evidence:
- cart-empty-after-checkout.png (annotated with arrows)
- network-har-checkout-failure.har (has the failing request + body)
- console-errors.txt (2× ReferenceError, 1× 500 from /api/orders)
- session-replay: https://sentry.io/replay/abc-123
- server logs: X-Request-Id: 9a8f-... (grep this in logs)
- short clip (<30s) showing the full flow: checkout-bug.mp4

Correlation ID: 9a8f-4c21-9e30 — links frontend error to backend log.

Rule of thumb: Attach the minimum evidence that proves the bug + lets the dev reproduce on their side. One sharp screenshot > ten verbose paragraphs. Include a correlation/request ID so they can pivot to backend logs instantly.

5. Severity vs Priority — two orthogonal axes

Severity = how bad the bug is. Priority = how fast we must fix it. A typo on the about page is low severity, low priority. A typo on the legal page before a regulated launch is low severity, high priority.

Bad

Severity: "High" (because I want it fixed fast)
Severity: "Low" (it only affects paying customers)
Severity: "Critical — ASAP — blocks everything"
(No rationale, no comparison, no business context.)

Good

Severity: High
  Rationale: Order confirmation email not sent blocks users from
  receiving their receipt, which is required for warranty claims
  and dispute resolution. Not a data-loss bug, so not Critical.

Priority: High
  Rationale: Affects 100 % of checkout flow since Tuesday deploy.
  Estimated 200 orders/day impacted based on /orders metrics.
  Support tickets filed: 14 in last 24h.
  Workaround: users can request receipt from support manually
  (but it takes ~1 business day).

Rule of thumb: State severity (impact to user) and priority (urgency to business) as two SEPARATE values, each with rationale grounded in data or spec. Avoid 'Critical + ASAP' without numbers — the more severe you claim, the more evidence you owe.

6. Reproducibility — always / sometimes / once

Always-reproducible bugs are debuggable. Intermittent ones demand different tooling (logs, tracing, flight recorders). Always state which category — developers pick the debug strategy from it.

Bad

Reproducibility: "sometimes"
Reproducibility: "when the stars align"
Reproducibility: "can't tell"
(no frequency, no attempted repro count)

Good

Reproducibility: 3/10 attempts (intermittent)

Notes:
- All failures occurred within 5 minutes after a deploy
- All successful attempts used the same fixtures, same steps
- Suspected correlation with cold Lambda (first-request latency)
- Did NOT reproduce in staging (2/0 attempts over 20 min)
- DID reproduce in production (3/10 over 30 min)

Logs attached: X-Request-Id for each failed attempt (3 IDs)
so the developer can pivot to backend traces.

Rule of thumb: Write the fraction (3/10) AND observations about WHEN it fires. 'Sometimes' is useless. 'Fails only on first request after a deploy, 30 % of the time' is a debugging seed. Attach correlation IDs so the developer can trace each failed attempt independently.

Copy-paste starter template

## Title
[<area>] <observable-behaviour> <under-precondition>

## Environment
- Browser: <name + version>
- Viewport: <W×H>
- Build/commit: <sha or staging timestamp>
- Account/role: <test user, role, if relevant>

## Reproduction
1. <concrete step>
2. <concrete step>
3. <concrete step>

Frequency: N/M attempts
Sample data:
  <paste minimum repro dataset>

## Expected
<what should happen, with spec citation if possible>

## Actual
<what actually happened, including side-effects>

## Evidence
- screenshot.png (annotated)
- network.har
- console-errors.txt
- X-Request-Id: <id>  ← links to backend logs
- session-replay / screen recording URL

## Severity / Priority
- Severity: <Critical|High|Med|Low> — <rationale>
- Priority: <Critical|High|Med|Low> — <rationale + metrics>

## Workaround
<if any known workaround, describe it>

## Notes
<anything else worth the reader's attention>

← Back to all Labs

From “need more info” to “merged in 24 h”

Title: "[checkout] Pay button submits twice when network >2s latency" Title: "[auth] Session cookie not rotated after login — fixation possible" Title: "[products] Catalog sort by price reverses every 2nd click" Title: "[api/v1/users] GET /users/:id returns 200 with null body on unknown id"

Reproduction: 1. Open Chrome 127, Incognito, size 1440×900 2. Navigate to https://stg.qa-practice.dev/products 3. Add 2× "Wireless Mouse" to cart 4. Click "Checkout" 5. In shipping form, fill all fields (sample data below) 6. Click "Continue to payment" 7. Observe: form resets AND cart is empty Sample data: { email: "t@t.dev", name: "Test User", phone: "+1 555 1234" } Frequency: 3/3 attempts. Persists across browser restart.

Expected: After clicking "Place order", the cart should clear, the user should see a confirmation page with order number, and an email should arrive within 60s. Actual: Cart remains full. No confirmation page renders. Order appears in user's /orders history (so the POST succeeded) but no email is sent. User tries again and gets a duplicate order. Specification source: /docs/checkout-flow.md#success-path or link to design mockup / Jira spec / etc.

Evidence: - cart-empty-after-checkout.png (annotated with arrows) - network-har-checkout-failure.har (has the failing request + body) - console-errors.txt (2× ReferenceError, 1× 500 from /api/orders) - session-replay: https://sentry.io/replay/abc-123 - server logs: X-Request-Id: 9a8f-... (grep this in logs) - short clip (<30s) showing the full flow: checkout-bug.mp4 Correlation ID: 9a8f-4c21-9e30 — links frontend error to backend log.

Severity: "High" (because I want it fixed fast) Severity: "Low" (it only affects paying customers) Severity: "Critical — ASAP — blocks everything" (No rationale, no comparison, no business context.)

Severity: High Rationale: Order confirmation email not sent blocks users from receiving their receipt, which is required for warranty claims and dispute resolution. Not a data-loss bug, so not Critical. Priority: High Rationale: Affects 100 % of checkout flow since Tuesday deploy. Estimated 200 orders/day impacted based on /orders metrics. Support tickets filed: 14 in last 24h. Workaround: users can request receipt from support manually (but it takes ~1 business day).

Reproducibility: 3/10 attempts (intermittent) Notes: - All failures occurred within 5 minutes after a deploy - All successful attempts used the same fixtures, same steps - Suspected correlation with cold Lambda (first-request latency) - Did NOT reproduce in staging (2/0 attempts over 20 min) - DID reproduce in production (3/10 over 30 min) Logs attached: X-Request-Id for each failed attempt (3 IDs) so the developer can pivot to backend traces.

Copy-paste starter template

## Title
[<area>] <observable-behaviour> <under-precondition>

## Environment
- Browser: <name + version>
- Viewport: <W×H>
- Build/commit: <sha or staging timestamp>
- Account/role: <test user, role, if relevant>

## Reproduction
1. <concrete step>
2. <concrete step>
3. <concrete step>

Frequency: N/M attempts
Sample data:
  <paste minimum repro dataset>

## Expected
<what should happen, with spec citation if possible>

## Actual
<what actually happened, including side-effects>

## Evidence
- screenshot.png (annotated)
- network.har
- console-errors.txt
- X-Request-Id: <id>  ← links to backend logs
- session-replay / screen recording URL

## Severity / Priority
- Severity: <Critical|High|Med|Low> — <rationale>
- Priority: <Critical|High|Med|Low> — <rationale + metrics>

## Workaround
<if any known workaround, describe it>

## Notes
<anything else worth the reader's attention>