Write a Bug Report That Survives the Handoff

A bug report often begins with “it stopped working.” That is a reasonable first signal, but it is not yet a reproducible problem. The next step is to turn the observation into a bounded experiment another person can run.

Start with the exact action that exposed the failure. “Open an existing record, change its title, and save” is more useful than “editing is broken.”

Separate expected and observed behavior

Write what should have happened and what actually happened. Keep the expectation tied to an established requirement or existing behavior. If the desired behavior is a new preference, describe it as a product decision rather than a regression.

Include the visible error or result, with sensitive data removed. A paraphrase such as “some database error” can discard the part that distinguishes one failure from another.

Record the environment that matters

Capture the application revision or release, relevant browser or runtime version, and the affected configuration. Do not dump an entire environment file. Most of its contents will be irrelevant, and some may be secret.

State whether the failure occurs with a particular account, data shape, or permission level. Use a sanitized fixture or description when the original data cannot be shared.

Reduce the sequence

Try to remove steps while preserving the failure. If the problem only appears after navigating between two views, that sequence matters. If it happens on a fresh page load, the earlier navigation may be noise.

Record frequency honestly: every attempt, intermittent, or observed once. An intermittent failure needs timestamps and correlation clues; it should not be described as deterministic because that would make the report easier to read.

Keep hypotheses separate

“Possibly a stale cache” can be a useful lead. It is not an observed fact. Label it as a hypothesis and include the evidence that suggested it.

Avoid fixing the report around the first explanation. If the next person disproves that explanation, they should still have a clear description of the failure to investigate.

End with a verification step

Describe how the fix will be accepted: repeat the original sequence and observe the expected result, then check the nearest related case that could regress. This turns the report into a useful test boundary.

A good bug report reduces rediscovery. It preserves the original failure well enough that the next person can spend their time explaining it rather than reconstructing it.