Writing reproduction steps another engineer can follow
The fastest way to lose a day on a bug is to ticket it with “sometimes fails in prod.” Good reproduction steps read like a lab protocol: specific, ordered, and honest about what you do not know.
Start with the observable symptom
State what a user or monitor sees: HTTP status, error code, blank field, delayed job. Avoid internal jargon in the first sentence. If the symptom is intermittent, quote frequency (“about two of fifty checkout attempts”) and the window you measured.
Name the environment precisely
Include region, deployment tag, feature flag states, and whether data is anonymised production copy or synthetic. If staging differs from production in a way that matters—smaller dataset, single node—say so upfront.
List inputs, not intentions
“Click checkout quickly” is vague. “Submit order with SKU 88421, quantity 3, card test 4111…, within 2 seconds of page load” is actionable. Attach sample payloads or redacted IDs in the ticket.
Capture time and ordering
Race bugs hide in assumptions about sequence. Note parallel actions, retries, and background jobs that ran in the same minute. UTC timestamps from logs beat local guesses.
Record negative results
What you tried that did not reproduce is as valuable as what did. It stops the next investigator from repeating your afternoon.
When documentation is enough
If your steps reproduce on a second machine without you present, you are ready for pairing or external help. If not, keep the ticket open and label unknowns explicitly—we would rather read “could not reproduce on staging” than inherit silence.