Desk reference / 01
For issue authors and the people
who need to reproduce their reports.
Make the failure repeatable.
A useful report lets another person recreate the conditions, see the mismatch, and tell what remains unknown.
Record the smallest failure you can demonstrate. A confident explanation is optional. The environment, the steps, and the observed result are the working material.
Eight fields, in reading order
Give each field one job.
- 1. Summary
- Name the action and the visible failure.“CSV export changes row order after sorting” is more useful than “Export broken.”
- 2. Context
- Record the product, version or commit, and environment that matter to the result.Include a browser or operating system only when relevant. “Latest” cannot identify a build later.
- 3. Preconditions
- List the starting state: settings, permissions, and minimal input.Prefer an invented fixture over a production record. Say which feature flags or filters are active.
- 4. Steps
- Number the actions someone must perform from that starting state.Keep one action per step. Include the action that reveals the failure, such as reopening a file.
- 5. Expected
- Describe the outcome you expected and the basis for expecting it.A requirement, documented contract, or established behavior is stronger than an unstated preference. Mark assumptions.
- 6. Observed
- Write the result you actually saw, including exact text or values where useful.“The file contains Cedar, Alder, Birch” is observable. “The cache is broken” is a hypothesis.
- 7. Reproduction
- Count failures and attempts; add a control and the limits of the check.Three failures in three attempts describe this check. They do not establish that every user is affected.
- 8. Evidence
- Point to a minimal fixture or a redacted capture and explain what it demonstrates.Say when an attachment is unavailable. Do not imply that a screenshot or log exists when it does not.
Keep observation separate from explanation.
Put a suspected cause in a clearly labelled note after the report. It should be possible to remove that note without losing the reproduction. A teammate can then test the cause without inheriting it as a fact.
- Reduce carefully. Remove one input or setting at a time. If the failure disappears, restore it and record the boundary.
- Use a control. Compare with one relevant change, such as an unsorted view. A passing control narrows the observation; it does not prove the cause.
- Protect the record. Remove access tokens, cookies, private URLs, personal data, and customer content. Inspect downloaded files as well as the text of the issue.
- State uncertainty. If you do not know the expected contract or affected versions, say so. A reproducible difference can be useful before it is confirmed as a defect.
For the broader product context, this guide to reading technical feedback in GitHub issues discusses why reproduction details are useful beyond a single fix.
Start with a blank record.
Copy the structure below, or download the JSON file. Empty values are deliberate: fill only what you know, and describe missing information in the relevant field.
{
"summary": "",
"context": {
"product": "",
"version_or_commit": "",
"environment": ""
},
"preconditions": [],
"steps": [],
"expected": "",
"observed": "",
"reproduction": {
"attempts": 0,
"failures": 0,
"control": "",
"scope_unknown": ""
},
"evidence": []
}