Bug Report Format

[Page or Feature] — [What's wrong] — [When or under what condition]

Checkout — 500 error on POST /orders when promo code contains a hyphen
Mobile nav — Hamburger menu not clickable when scrolled past 200px
Login — "Forgot password" link 404s on production (works in staging)

Bug in checkout                   ← too vague
Doesn't work                      ← what doesn't work?
Help                              ← please no
Promo code issue                   ← which issue, on what code?

Preconditions:
  - Logged in as qa.user@example.com on staging (build 1.42.0)
  - Cart contains exactly 1 item: SKU "WIDGET-42", quantity 1, price $19.99

Steps:
  1. Open https://app-staging.example.com/checkout
  2. In "Promo code" field, enter: SUMMER-2025
  3. Click "Apply"
  4. Wait for promo to be accepted (success toast appears)
  5. Click "Place order"

Expected:
  - Order is created and receipt page (/order/:id) loads within 3 seconds.
  - Network: POST /api/orders → 201 Created.

Actual:
  - Red toast: "Something went wrong. Please try again."
  - Network: POST /api/orders → 500 Internal Server Error.
  - Server log: "ValidationError: invalid promo code format" (link to log entry below).
  - Order not created (verified in admin panel — no new row).

Summary: [Page] — [Visual or interaction issue] — [Condition]

Environment:
  - Build: [version or git SHA]
  - Browser: [Chrome 132 / Safari 17 / Firefox 122]
  - OS: [macOS 14.7 / Windows 11 / iOS 17]
  - Viewport: [1440×900 / 375×667]

Preconditions:
  - [User state: logged in/out, role, account type]
  - [App state: feature flag X enabled, cart with N items, etc.]

Steps to Reproduce:
  1. [Specific action]
  2. [Specific action]
  3. [Specific action]

Expected Result:
  [Pixel-precise or behaviour-precise description]

Actual Result:
  [What you observe]

Evidence:
  - Screenshot: [URL or attachment]
  - Screen recording: [URL or attachment]
  - DOM snapshot or computed style: [if relevant]

Summary: [Endpoint] — [Status code or response issue] — [Condition]

Environment:
  - Service: [name + build/version]
  - Region: [us-east-1 / eu-west-2 / etc.]
  - Auth: [token type + scope, or "anonymous"]

Request:
  Method: POST
  URL: https://api.example.com/v1/orders
  Headers:
    Authorization: Bearer eyJhbG…
    Content-Type: application/json
    X-Request-Id: 7f1a-…

  Body:
    {
      "sku": "WIDGET-42",
      "promo": "SUMMER-2025"
    }

Expected Response:
  Status: 201 Created
  Body:
    {
      "id": "ord_…",
      "total": 14.99
    }

Actual Response:
  Status: 500 Internal Server Error
  Body:
    {
      "error": "ValidationError",
      "message": "invalid promo code format"
    }

Evidence:
  - Server log: [link to log line / Datadog query]
  - HAR file: [attachment]
  - Reproduction count: 5 of 5 attempts

Summary: [Page or endpoint] — [Metric exceeded] — [Condition]

Environment:
  - Build: [version]
  - Network: [throttling profile or "no throttling"]
  - Device: [hardware specs if relevant]
  - Concurrent users: [load if applicable]

Preconditions:
  - [Cache state: cold/warm]
  - [Account size: e.g., user has 5,000 saved items]

Steps to Reproduce:
  1. [Specific action]
  2. [Specific action]

Expected:
  - [Metric]: [target] (e.g., LCP under 2.5s, p95 latency under 200ms)

Actual:
  - [Metric]: [observed value]
  - Trend: [is it consistent, getting worse, only at peak hours?]

Evidence:
  - Lighthouse report: [URL or attachment]
  - WebPageTest run: [URL]
  - APM trace: [link to Datadog/New Relic trace]
  - Reproduction count: [N of M attempts]

Summary: Login broken
Severity: Major
Steps: I can't log in. Fix it.

Summary: Login — "Sign in" button does nothing on first click after fresh page load

Severity: Major
Priority: P1
Environment:
  - Build: 1.42.0 (staging)
  - Browser: Chrome 132 on macOS 14.7
  - Reproduces on Firefox 122 and Safari 17 — all consistent

Preconditions:
  - Hard reload of /login (Cmd+Shift+R)
  - Account: qa.user@example.com / Secret!23

Steps to Reproduce:
  1. Hard-reload https://app-staging.example.com/login
  2. Enter qa.user@example.com in Email
  3. Enter Secret!23 in Password
  4. Click "Sign in" once

Expected:
  - User is redirected to /dashboard within 2 seconds.

Actual:
  - First click on "Sign in" does nothing.
  - Second click works — user is redirected normally.
  - Reproduces 10 of 10 attempts on a fresh page load.
  - Console shows: "Cannot read property 'token' of undefined" on first click only.

Evidence:
  - Screen recording: [link]
  - Console log: [attachment]
  - Network HAR: [attachment] — first click never fires POST /auth/login