How to write a bug report
A good bug report lets someone who was not there see the same bug in under five minutes. Seven fields do most of the work.
The seven fields
- Title. Say what is wrong and where, in one line: “Saving a task with an emoji in the title shows a blank page”. Not “Save broken”.
- Environment. Version or commit, browser or device, operating system, and whether it is production or local. A bug that happens only in Safari is a different bug.
- Steps to reproduce. Numbered, starting from a known place such as a fresh login. Each step is one action. If you cannot reproduce it, say how often it happened.
- Expected result. What you thought would happen, in one sentence.
- Actual result. What happened instead, in one sentence. Quote the error message exactly.
- Evidence. A screenshot, a short recording, a log excerpt or a failing request. Paste the text of the error, not only a picture of it.
- Impact. Who is affected and what they cannot do. This is what lets someone else decide how soon to fix it.
A template to copy
Title: <what is wrong, and where>
Environment: <version, browser/device, OS, production or local>
Steps to reproduce:
1. <start from a known place>
2. <one action>
3. <one action>
Expected: <one sentence>
Actual: <one sentence, with the exact error text>
Evidence: <screenshot, recording, log excerpt>
Impact: <who is affected, what they cannot do>
Frequency: <always, sometimes (how often), once>A weak report and a strong one
| Item | Weak | Strong |
|---|---|---|
| Title | Export is broken | CSV export of a filtered board returns every task, not the filtered ones |
| Steps | Try to export | 1. Open a board. 2. Filter by tag “api”. 3. Choose Export, CSV. |
| Actual | Wrong data | The file has 212 rows. The board shows 14. |
| Impact | (none) | Anyone sending a filtered export to a client sends the whole backlog. |
Before you file it
- Search for it first. Someone may have reported it already; add what you know to that report instead.
- Reproduce it once more on a clean session. Half of all “bugs” are a cached state.
- One bug per report. Two problems in one report get fixed one at a time and closed once.
- Leave out guesses about the cause unless you label them as guesses.
When an agent files it
A coding agent that finds a bug in passing should follow the same seven fields, and run a duplicate check before it files. BugBoard exposes that check to agents over MCP as check_duplicates, so the agent does not add a second copy of a report that exists.