The ticket had bounced three times. The developer moved it to "cannot reproduce," QA moved it back with "still happens for me," and the bug sat live in production while everyone argued in the comments.
I've watched this loop on more than one project, and the missing piece was almost never the steps. It was the build number, the test data, and the evidence nobody attached. On one project where we enforced context and attachments as a hard requirement, the ticket reopen rate dropped by 80%. On another, by 50%.
The reports didn't get longer. They got sufficient. Here's the standard I use, what it actually changed on real projects, and what it costs.
"Reproducible" means rebuilding state, not replaying clicks
When a developer can't repro your bug, it's rarely because they can't follow numbered instructions. It's because they can't rebuild the state the bug lives in: your role, your tenant, your data shape, your feature flags, your build.
The research here is old but has never been contradicted. In the classic "What Makes a Good Bug Report?" survey (FSE 2008) of Apache, Eclipse, and Mozilla developers, steps to reproduce ranked as the most useful element of a report — cited by 83% of developers — and incomplete information was the most severe problem they faced. The uncomfortable finding: when reporters were asked what developers need, their answers correlated with developers' actual rankings at 0.839. Reporters know what's needed. They just don't attach it.
I hit the same wall on an art management and sales platform we tested. Reports frequently contained insufficient context, carried no screenshots or videos, reopens were high, and reproduction dragged. Better prose in the steps field would have fixed none of that.
And this is expensive time to waste. In a 2021 Rollbar survey of 950 developers, 26% said they spend up to half their working time fixing bugs. Every failed repro attempt is that budget burning on state archaeology instead of the actual fix.
Some defects genuinely are environment-bound and won't reproduce anywhere but one machine — I'll get to those. But most "cannot reproduce" resolutions are state-reconstruction failures, and those are on the report.
The minimum sufficient report
Minimum. Not maximum. Five fields, each pre-answering a question the developer would otherwise ask in the comments a day later.
Build and environment — never "latest"
"Latest" is a different build by the time triage happens. Pin it:
- build number or commit hash
- environment (prod, staging, which integration env)
- browser and version, OS, device for anything client-side
A developer who spends an hour chasing a bug that's already fixed on main will not thank you for "latest."
Preconditions and test data
This is the field that decides reproducibility more often than any other, and it's the one most templates treat as optional. State the role, the tenant or account type, the relevant feature flags, and the exact record you used — with an anonymized ID, not a screenshot of personal data.
Data shape matters more than data existence. "A user with zero saved addresses" and "a user with 400 saved addresses" are different bugs waiting to happen in the same form.
Atomic, numbered steps from a known start state
Start from a state anyone can reach: "log in as org admin, open the dashboard." Then one action per step. A compound step like "create and publish a listing with images" hides the exact action that triggers the failure.
Expected vs. actual, stated separately
A study of non-reproducible bugs in Firefox and Eclipse (ICSME 2020) found that 65% of the reports missed the correct expected behavior and 49% contained no steps to reproduce at all. Expected behavior isn't your opinion — anchor it to the spec, the acceptance criteria, or the previous build's behavior, and link it.
Evidence, sized to severity
- screenshot for anything layout or content
- video for anything involving timing, ordering, or interaction
- logs, console output, and request IDs for anything server-side or intermittent
On a CTEM platform in the cybersecurity space, our unified bug-report standard required "clear reproduction steps, clear expected results, and necessary attachments such as videos, screenshots, or logs." On the art platform we got to attachments on 100% of reports. A video costs two minutes to record. A reopen cycle costs two days of calendar time.
A template alone won't lower your reopen rate
Here's the assumption I want to kill: that you can paste a good template into Confluence and reporting fixes itself. Templates collect fields. Workflows enforce them.
Every engagement where the metrics actually moved changed the workflow, not just the form:
- On the CTEM platform, the report standard shipped together with a redesigned Jira workflow, testing moved from UAT into integration and staging, and AI-assisted test design. Reopen rate fell 80%, defect reproduction time fell 30%, overall testing time fell 40%.
- On BiznessApps, reports had been "unstructured and uninformative," so yes — a bug report template was created. But the Jira workflow was also updated, all legacy issues were retested, and stale tickets were purged. Across the engagement: 1,700+ issues reported, support issues down more than 50%, zero critical production issues post-release.
- On the art platform, the Jira redesign came with a user-story template and the mandatory-attachment rule. Reopens down 50%, lost and unclear tickets down 95%.
I'll be straight about the evidence: several variables changed at once on every one of these projects, so no single number isolates the template. That's exactly the point. The standard worked because it lived in the tracker — required fields at creation, a triage gate that bounces a contextless report back to the reporter instead of forward to a developer — not on a wiki page nobody opens.
Write it while the bug is still on screen
The worst reports are written from memory an hour later. The state you needed is gone the moment you navigate away. My order of operations:
- Record the video or grab the screenshot first, before touching anything.
- Open the console and network tab and save the errors and the failing request before you reload.
- Copy the request ID or correlation ID from the failing call.
- Note the timestamp, so whoever picks it up can find the exact window in the server logs.
- Only then write the steps, walking backwards from what's on screen.
On NEXSYS-ONE we made it compulsory to include all essential details and attachments in bug reports, alongside refined task descriptions. On that project, 70% of blocker, critical, and major bugs were caught at the development stage — a figure that also reflects a full automation and CI build-out, not report quality alone. But evidence captured at find-time is what made those dev-stage reports actionable without a round-trip.
Bugs that genuinely don't reproduce
A 2022 large-scale study estimates about 17% of reported bugs can turn out non-reproducible, and in the Firefox dataset bug intermittency was the single largest cause at roughly 26%. So an intermittent bug is not a failed report — it's a different kind of ticket.
File it as an investigation, not a defect, and give it:
- observed frequency ("3 of 10 attempts")
- the environment matrix you tried (browsers, accounts, data variants)
- logs and a correlation ID from at least one failing occurrence
- timestamps for every occurrence you saw
And never close "cannot reproduce" without recording what was tried. An empty closure guarantees the next reporter starts from zero. One caveat from experience: unbounded investigation tickets rot at the bottom of the backlog. Timebox them — one more occurrence with full evidence, or close with the investigation log attached.
What the evidence bar costs
The bar isn't free, and pretending otherwise is how standards die:
- Video, log pulls, and redaction cost real minutes per report. At the volumes we logged — 1,000+ bugs on the art platform, 1,700+ issues on BiznessApps — those minutes compound.
- A cosmetic typo doesn't earn a video. Scale evidence to severity, or reporters will (rightly) start ignoring the rule.
- Over-specified steps go stale as the UI changes. Steps should reference intent ("open the billing settings"), not pixel positions.
- Attachments carry PII risk in regulated products. Anonymize test data, redact screenshots, and treat logs as sensitive by default.
- Documentation discipline is an ongoing cost, not a one-time setup. On Catalyst, a therapy-practice product, two QA engineers spent five years maintaining specifications and acceptance criteria alongside ~1,000 test cases. The payoff was releases that shipped on schedule — the first one three months in, a week early — but nobody should pretend that maintenance was free.
Set against what defects cost overall — CISQ estimated poor software quality cost the US $2.41 trillion in 2022 — minutes per severe bug is a trade I'll take every time.
The checklist, in priority order
When I review a report before it goes to a developer, I check in this order — because this is the order in which things kill reproducibility:
- Build and environment — pinned, not "latest."
- Preconditions and test data — role, tenant, flags, the exact record.
- Steps — atomic, numbered, from a state anyone can reach.
- Expected vs. actual — separate, with the expected behavior sourced.
- Evidence — sized to severity: screenshot, video, logs.
Then the part that actually moves the metrics: put the standard in the ticket workflow, with required fields and a triage gate, not in a wiki. And accept the trade-off honestly — this bar costs minutes on every serious bug, and it isn't worth paying on every cosmetic one.
Reach for this standard when reopen rates and reproduction time are eating your sprints. Skip the heavyweight version for triage-only and cosmetic issues — a pinned build and one screenshot is enough there.
Top comments (0)