Describing the Problem

Expected / Actual / Steps to Reproduce / Environment — the four components of a useful bug report.

A complete bug description:

**Expected:** Clicking "Log in" with valid credentials navigates to the dashboard.
**Actual:** The button shows a spinner for 5 seconds, then displays:
  "TypeError: Cannot read properties of undefined (reading 'token')"
**Steps to reproduce:**
1. Go to https://app.example.com/login
2. Enter user: test@example.com, password: Test1234!
3. Click "Log in"
**Environment:** Chrome 122, macOS 14.3, staging environment (not prod)

Why each section matters:
• Expected: establishes the correct behavior; without this, it's unclear if the reporter understands the feature
• Actual: the specific symptoms, exact error message, observable behavior
• Steps to reproduce: enables the next developer to reproduce the bug on their machine
• Environment: narrows down whether it's a browser/OS issue, or environment-specific (staging vs. prod)

One-sentence bug reports (like "login is broken") force the investigating developer to ask follow-up questions, doubling the time to resolution.

Option C — a specific, measurable, actionable problem statement.

What makes it good:
1. Specific endpoint: GET /api/search (not just "the API")
2. Quantified actual: 2.3s average (not "slow" or "sometimes slow")
3. Measurement method: "over 100 requests" — statistically meaningful
4. Specific expected: <500ms per SLA — references the service level agreement
5. Full environment: OS, Node version, infrastructure, database — all reproduction-critical

How to improve vague bug reports:
• "slow" → "X ms average, Y ms at P99 (99th percentile)"
• "sometimes" → "reproducible when [condition]" or "occurs ~30% of requests in load test"
• "the API" → "GET /api/endpoint?param=value"
• "doesn't work" → specific error message or behavior
• "in production" → specific production configuration, region, or affected users

Rule: if you cannot state the Expected and Actual in concrete, measurable terms, you do not yet have enough information to file an actionable bug report.

Option B — complete, numbered steps to reproduce with a clear expected/actual pair at the end.

Steps to Reproduce (STR) format:
1. Numbered list — one discrete action per step
2. Specific: use exact values ("50 characters", not "a long string")
3. Start from a known state (navigate to /settings/profile, not "go to the settings")
4. Include the expected result after the final step
5. Include the actual result (what actually happened)

Good STR principles:
• Reproducible on a fresh browser session (no assumed state from previous steps)
• Another developer can follow them without asking for clarification
• Include any required setup: "Requires an account with the 'admin' role" or "Reproduce only in Firefox"
• If intermittent: "Reproducible ~70% of the time; refresh and retry if it works first time"

The goal is: the developer receiving the bug report should be able to reproduce the issue in under 5 minutes following only the STR.

Intermittent bug — a bug that does not consistently reproduce. It requires different documentation than a deterministic bug.

How to describe intermittent bugs:

**Frequency:** ~1 in 10 attempts
**Pattern observed:** More likely under load (>5 concurrent users in staging); 
  not observed with single user
**When it occurred:** Steps 1–4 above; sometimes step 3 completes but step 4 fails
**Logs available:** Yes — see attached log snippet, timestamp 14:32:08 UTC
**Screen recording:** [link]

Note: if unable to reproduce immediately, reload the page and retry.

Key phrases for intermittent bugs:
• "Reproduces approximately X% of the time"
• "Observed when [condition] — not observed without it"
• "We believe it is timing-related / load-related / environment-specific"
• "We have a screen recording of one occurrence"
• "Logs captured from the occurrence at [timestamp]"

An intermittent bug without logs or a reproduction rate is the hardest type to investigate. If you cannot reproduce it, capturing logs and metrics when it does occur is the most valuable contribution you can make.

Option C — isolated to a specific function and the specific edge case that triggers it.

Phrases for isolating a bug's location:
• "isolated to" — narrowed down to a specific component/function/line
• "reproduces only when" — the specific triggering condition
• "I ruled out X and Y — the issue is in Z" — shows reasoning
• "occurs at line 87 in src/billing/tax.js" — exact file + line reference
• "the edge case where" — describes the boundary condition
• "limited to" — affects only a subset of cases

Describing scope of impact:
• "Affects all users with discount codes > 50%"
• "Affects only the checkout flow, not the cart preview"
• "Observed in Chrome 122 only — not Safari or Firefox"
• "Occurs only with items in the 'clearance' category"

Precise isolation language saves an investigating developer from re-doing work you already did and enables them to jump directly to the relevant code.

Option C — a specific impact statement with affected users, timeline, quantified business impact, and data safety confirmation.

Impact statement template:
• WHO: "all EU users" / "users with role 'admin'" / "users who signed up before 2024"
• WHAT: "attempting checkout" / "viewing the dashboard" / "exporting reports"
• SINCE WHEN: specific timestamp — "since 09:15 UTC" — enables root cause timeline analysis
• SCALE: "~340 failed transactions" — quantified, even if approximate
• BUSINESS IMPACT: "~£4,200" — translates technical failure into business terms
• DATA SAFETY: "No data loss" / "Orders may have duplicate charge" — critical for severity triage

Why "it's pretty bad" is insufficient:
• Stakeholders cannot make prioritisation decisions without numbers
• Engineers cannot scope the fix without knowing impact boundaries
• "Bad" is subjective — one engineer's "bad" is another's "critical P0"

Quantifying impact is a key professional skill that distinguishes senior from junior communication in incidents and bug reports.