The Incident That Changed How I Report Bugs
Monday morning, 9:15 AM. A support ticket arrives: "Users can't log in — getting an error." No screenshot. No error message. No user ID. Just a panicked subject line.
Three engineers dropped everything. We checked auth service logs, database connections, deployment status. After 90 minutes, someone noticed the error actually said "rate limit exceeded" — a customer had hit our API 300 times in a minute. A five-minute fix. Three hours wasted.
That day I wrote a personal checklist. Over the years it evolved into the five questions I now ask before filing any bug report. It's saved me — and the engineers I work with — hundreds of hours.
Question 1: What Exactly Did You Do and What Exactly Happened?
Vague reports are the enemy. "The app crashed" is useless. "Clicked 'Save' on the invoice form, got a 500 error with correlation ID abc-123" is actionable.
Write down the exact steps, in order. Include input values, button names, and any error codes. If it's an API, include the exact curl command or request payload. If it's a UI, include the browser version, OS, and whether it happens in incognito mode.
Here's a minimal template I use:
## Steps to reproduce
1. Open Chrome 120 on macOS 14.2 (incognito)
2. Navigate to https://app.example.com/invoices
3. Click 'Create New Invoice'
4. Enter customer email: test@example.com, amount: 100.00
5. Click 'Save'
6. See error: 'Something went wrong' (no correlation ID)
## Expected
Invoice is created and shown on the list.
## Actual
Blank page with error toast. Network tab shows POST /invoices returning 500.Question 2: Can You Reproduce It Consistently?
If you can reproduce it every time, great — skip ahead. But if it's intermittent, that's the most valuable detail you can provide.
Intermittent bugs are often caused by race conditions, caching, or specific data combinations. Document the frequency (e.g., 'happens 1 in 20 attempts') and any pattern you notice (e.g., 'only when the user's account has more than 10 invoices').
I once saw a bug that only happened on Tuesdays — turned out a cron job restarted a service that cleared an in-memory cache. Without that frequency note, the engineer would never have looked at the cron schedule.
Pro tip: If you can't reproduce it, try different environments. Does it happen on Chrome but not Firefox? On mobile but not desktop? On the staging server but not production? Each 'no' is a clue.
Question 3: What Changed Recently?
Most bugs are introduced by a recent change. Check the deployment history of the affected service. Look at the commit log for the last 24 hours. Did a colleague push a change? Was a feature flag toggled? Did a third-party API update their SDK?
In one memorable incident, a payment integration broke silently because the payment gateway deprecated an API endpoint. The developer who made the change had left a note in Slack but no one saw it. A simple check of the changelog would have saved a day of debugging.
Include any relevant change details in your report. If you can identify the exact commit that caused the regression, you're a hero.
Question 4: Have You Collected the Evidence?
A bug report without logs, screenshots, or network traces is a guess. Before hitting submit, gather as much evidence as you can:
- Screenshots or screen recordings (highlight the error)
- Browser developer console output (network tab, console errors)
- Server logs (if you have access)
- Correlation IDs or request IDs
- The exact time the bug occurred (UTC preferred)
If it's a backend bug, include the request headers, payload, and response. If you're using a tool like curl, paste the exact command. If it's a mobile app, include the device model, OS version, and app version.
# Example: capture a failing API call
curl -v -X POST https://api.example.com/invoices \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","amount":100.00}' \
-o response.json 2>&1 | tee curl_output.txtQuestion 5: Is This Actually a Bug or a Misunderstanding?
Before filing, ask yourself: could this be expected behavior? Maybe the feature works as designed, but the UI is confusing. Maybe the documentation says the limit is 100, but you expected 1000.
Check the documentation. Look at the existing tests. Ask a colleague quickly. I once filed a bug about missing data, only to discover a filter was enabled by default. The filter was intentional. I wasted an hour of an engineer's time.
If you're unsure, phrase it as a question: 'Is it expected that...?' That invites a conversation, not a fire drill.
The best bug reports are the ones that never need a follow-up question.
Putting It All Together: A Template
Here's the template I use now. It forces me to answer all five questions before submitting:
## Summary
[One-line description of the bug]
## Environment
- Service/App version: [e.g., v2.3.1]
- Browser/OS: [e.g., Chrome 120, macOS 14.2]
- Deployment: [e.g., production, us-east-1]
## Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. ...
## Expected vs Actual
- Expected: [what should happen]
- Actual: [what actually happens]
## Evidence
- Screenshot/screen recording: [link]
- Logs: [paste relevant lines]
- Correlation ID: [abc-123]
- curl command: [if applicable]
## Frequency
- [ ] Always happens
- [ ] Intermittent: [describe frequency]
## Recent Changes
- [Link to relevant deploy/commit/feature flag]
## Impact
- [Who is affected? How many users?]
- [Is there a workaround?]The Payoff: Less Back-and-Forth, Faster Fixes
Faster bug resolution when using structured reports (internal data, 2023)
After I started using these five questions, the number of follow-up comments on my bug reports dropped to near zero. Engineers started thanking me. My bugs got fixed in hours instead of days. And I stopped being the person who triggered a 3-hour incident for a rate limit error.
Next time you encounter a bug, take five minutes to run through this checklist. Your future self — and the engineer on the other end — will thank you.
Frequently asked questions
What should I do if I can't reproduce the bug consistently?
Document the exact environment (browser, OS, network, service version) and the frequency (e.g., 'happens 1 in 50 requests'). Include any logs, screenshots, or network traces. The engineer can then look for patterns in monitoring data.
How detailed should the steps to reproduce be?
As detailed as a script. Include every click, keystroke, and API call. If it's a web app, note the browser version, extensions, and whether incognito mode changes behavior. For APIs, provide the exact curl command or request payload.
Should I include personal data like passwords in the bug report?
Never. Redact sensitive information. Use placeholders like 'user@example.com' and 'password123'. If the bug depends on specific data, generate a synthetic dataset that reproduces the issue and attach it.
What if the bug is intermittent and I can't get logs?
Enable verbose logging or add temporary log statements. If you can't modify the code, use a tool like 'curl -v' or browser devtools to capture network traffic. Record a video if needed — a 10-second clip can save an hour of debugging.