How to write a bug report email that gets a production issue fixed today
Engineers who do not know you, in the middle of a sprint, will triage your email in about ten seconds. If the impact is in the first line and the steps to reproduce are easy to follow, it gets picked up. If it opens with pleasantries and a story, it waits. This guide shows the difference.
The task
The briefCustomers on Android cannot complete payment: the app returns to the cart with no error message, and support has had 14 calls since yesterday evening. Nobody on the engineering team has noticed. Write the email that gets this looked at today.
The engineering team that owns the checkout service. They do not know you and they are mid-sprint.
State the impact in numbers up front
Describe exactly what the user sees
Give the steps to reproduce it
Say what you need and by when
Length
110–170 words
Suggested time
20 minutes
Level
Medium
Planning tip: Impact first, then what you observed, then how to reproduce it, then what you need. Never open with "hope you are doing well" on an outage.
What a strong answer does
The impact is the first line, in numbers: who is affected, how many, since when, and what it is costing. A count of support calls is a priority; ‘there seems to be an issue’ is not.
The symptom is described exactly as the user experiences it: what they tap, what happens, what they expected, and the fact that no error appears.
Steps to reproduce are numbered, start from a clean state, and include the device, OS version and app version if you have them.
Observation and guess are kept apart. ‘Every report so far is from Android’ is an observation; ‘I think the last release broke it’ is a guess, and is labelled as one.
The ask is explicit: an acknowledgement today, an owner, and a fix or a workaround by a stated time.
The tone is neutral: no blame, no drama, no capital letters. The numbers carry the urgency.
It survives forwarding. Someone who reads only the subject and the first two lines knows enough to route it.
How to structure it
- 1
Subject line
10–16 wordsSeverity, area and symptom in one line: ‘[P1] Android checkout: payment returns to cart, no error, [n] reports’.
- 2
Impact
25–35 wordsWho is affected, how many, since when, and what it costs: lost orders, support load. One or two sentences.
- 3
What the user sees
25–35 wordsThe exact behaviour, the expected behaviour, and any error message, or the absence of one.
- 4
Steps to reproduce
30–45 wordsA short numbered sequence: device, OS and app version, then each action. Add anything you have already ruled out.
- 5
What you need
20–30 wordsThe specific ask and the deadline, plus what you can supply straight away: call notes, user IDs, screenshots.
- 6
Sign-off
5–10 wordsName, team, and the fastest way to reach you.
Useful phrases
Frames, not finished sentences: put your own details where the [brackets] are, and use only the ones that fit what you are saying.
Impact first
- Since [time] on [day], [group of users] have been unable to [action].
- Support has logged [number] contacts about it so far, and the number is still rising.
Describing the symptom
- After [action], the app goes back to [screen] without showing any error.
- Expected: [result]. Actual: [result].
Reproducing it
- To reproduce: 1) [step] 2) [step] 3) [step].
- Seen on [device], [OS + version], app version [x.y.z].
- I couldn’t reproduce it on [other platform], which may help narrow it down.
Observation versus guess
- Every report we have so far comes from [platform].
- My guess, and it is only a guess, is that it started with [release or change].
The ask
- Could someone confirm by [time] today that it is being looked at?
- I can send call notes and the affected [order/user] IDs right away.
- I’m on [channel/number] all day if a quick call is easier.
Common mistakes, and how to fix them
Opening with ‘Hope you are doing well’ during an outage.
It delays the one fact that matters and signals that this is routine. Engineers working through a full inbox may never reach line three.
Fix: Make the first line the impact, in numbers. Courtesy can go in the close.
‘Payment is not working.’
Engineers cannot act on it. Which platform? Which step? What happens instead? Every missing detail costs a reply and a few hours.
Fix: Describe what the user does, what happens, and what should happen.
Presenting a guess as a diagnosis: ‘Your last release broke payments.’
It may be wrong, it sends the team down the wrong path, and it puts them on the defensive.
Fix: Report what you observed, and label any theory as a theory.
Shouting instead of showing: ‘URGENT!!! PLEASE FIX ASAP!!!’
It reads as panic, and teams learn to discount senders who use it.
Fix: Let the numbers carry the urgency, and put a severity label in the subject.
No ask, or no deadline.
An email that only describes a problem can be read, agreed with and left. Without a ‘by when’, today quietly becomes this sprint.
Fix: Say what you need, from whom, and by what time.
Present tense with ‘since’: ‘We are facing this issue since yesterday’, ‘Customers are unable to pay since 6 pm’.
Speakers of Hindi, Spanish, French, German and Chinese, among others, often use the present with ‘since’. It is understood, but a technical email should be precise about time.
Fix: Use the present perfect: ‘Since 6 pm yesterday, customers have not been able to pay.’
Before you submit: a self-check
Does the first line say who is affected, how many and since when?
Could an engineer who has never met you reproduce it from your steps?
Have you kept what you saw separate from what you suspect?
Is there a specific ask with a time?
Would the subject line alone get it routed to the right team?
Is the tone neutral, with no blame and no capital letters?
Questions people ask
What should a bug report email include?
Five things, in this order: the impact (who, how many, since when), what the user sees compared with what should happen, numbered steps to reproduce with device and version, anything you have already ruled out, and what you need by when. Attach screenshots, recordings or IDs instead of describing them.
How do I get an engineering team to prioritise my bug?
Quantify the impact. Teams prioritise by severity and reach, so a count of blocked users or support calls moves a bug up the queue in a way adjectives cannot. Make it easy to act on, with steps that reproduce it and a clear owner, and set a reasonable deadline.
Should I email or use the bug tracker?
If your company has a tracker or an incident channel, use it, and if nobody responds, send an email that links to the ticket. The writing rules are the same either way: impact first, facts second, a clear ask.
Is it rude to email a team I don’t know about their bug?
Not if the email is factual and neutral. You are helping them find a problem their users are already having. Avoid blame, stick to what you observed, and thank them at the end.
Report a production bug to a team that has not seen it
110–170 words · 20 minutes · Medium. Free to start; you need a TalkDrill account to submit, not to read this guide.
Scored by AI on TalkDrill on
- Task response25%
- Organisation20%
- Grammar20%
- Vocabulary15%
- Mechanics (spelling and punctuation)10%
- Tone10%
