## TL;DR
Engineers act on bug reports they can reproduce in under five minutes. Write the shortest path from a fresh state to the broken behavior, include exact environment details, and state expected vs actual behavior in one line each. A report with repro steps, a screenshot or recording, and a severity signal gets picked up; a paragraph of prose gets filed away.

## The query

```text
writing bug reproduction steps for engineering handoff
```

## Use this when

- You are escalating a customer-reported bug to engineering
- Engineering keeps kicking back your bug reports as unreproducible
- You want a bug report template for the support team
- A QA or triage rubric needs a repro-quality bar

## Not for

- Customer-facing workaround messages
- Feature requests or product feedback
- Postmortems after an incident
- Writing the actual code fix

## Steps

### 1. Confirm the bug on your own machine first

Before writing anything, try to hit it yourself with the user's account state or a fresh test account. A repro you have personally run is ten times more credible.

Expected output: you have seen the bug happen at least once, or you note "could not reproduce locally" honestly.

### 2. Reduce it to the shortest path

Cut every step that is not needed. If the bug still happens without step 4, delete step 4. Three to five steps is the sweet spot.

Expected output: a numbered list of steps starting from a defined fresh state (logged in, empty cart, etc).

### 3. Pin the environment

App version, browser and version, OS, user role, account plan, any relevant settings or flags. Copy the exact values, do not paraphrase.

Expected output: an Environment block with exact versions and settings, no "latest" or "recent".

### 4. State expected vs actual in one line each

"Expected: invoice exports as PDF with line items. Actual: exports as a blank PDF." One line each, no adjectives.

Expected output: two sentences, zero ambiguity about what correct behavior looks like.

### 5. Attach evidence

Screenshot of the broken state, screen recording of the repro, console or network errors if any. Attach the raw file, not a pasted description.

Expected output: at least one visual artifact showing the bug.

### 6. Add the severity signal

How many users are affected, whether there is a workaround, and whether data loss or billing is involved. This is what decides the queue order.

Expected output: one line with user count, workaround yes/no, and data/billing impact.

## Bug report template

```text
Title: [short symptom], e.g. invoice export returns blank PDF

Environment: app v4.2.1, Chrome 128, macOS 14, Pro plan

Steps:
1. Log in as a Pro user
2. Go to Billing, click Export invoice for September
3. Open the downloaded file

Expected: PDF shows line items and totals
Actual: PDF is completely blank

Evidence: [screenshot / recording]

Severity: 12 users reported this week, no workaround, billing-related
```

## Variant phrasings

### bug report template for support to engineering handoff

Use the template above verbatim as your team's macro. Fill every block, every time.

### how to write good bug reports for developers

Same structure. The single biggest upgrade is step 2: most bad reports have a 15-step novel where a 4-step repro exists.

### what to include when escalating a bug to engineering

Steps, environment, expected vs actual, evidence, severity. If you only have four of the six, say which one is missing and why.

## Why it happens

Support reports land in engineering's queue competing with feature work, and engineers triage by reproduction cost. A report that takes two minutes to reproduce gets investigated today; a report that takes an hour of guessing gets scheduled for never. The repro steps are not documentation, they are the argument for why this bug deserves attention now.

## Edge cases

- Intermittent bugs: include frequency ("3 of 10 attempts") and anything that correlates (time of day, data volume, specific account state).
- Bugs you cannot reproduce: say so explicitly, and hand over everything you do have, logs, user state, timestamps. An honest "could not reproduce" beats a fake repro.
- Data-sensitive bugs: strip PII before attaching evidence, or note that the engineer needs the user's consent to look at the account.
- Third-party bugs: same template, but the escalation target is the vendor ticket, and severity signal matters even more.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_haRjeFkoFbRZtUNa-_mbQw