Skip to content

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.

Written by the BugBoard team. 5 minute read. Updated 14 November 2026.

The seven fields

  1. 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”.
  2. 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.
  3. 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.
  4. Expected result. What you thought would happen, in one sentence.
  5. Actual result. What happened instead, in one sentence. Quote the error message exactly.
  6. 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.
  7. 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

ItemWeakStrong
TitleExport is brokenCSV export of a filtered board returns every task, not the filtered ones
StepsTry to export1. Open a board. 2. Filter by tag “api”. 3. Choose Export, CSV.
ActualWrong dataThe 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.