BugTape blog

A bug report template your coding agent can use

A free, copy-paste bug report template for Claude Code, Cursor or Codex: steps, evidence, missing evidence, guesses, next test and acceptance check.

Short answer: copy the template below, fill it in, and paste it into Claude Code, Cursor or Codex. It keeps eight things apart: what the user did, what happened against what you expected, the environment, the evidence you have, the evidence you are missing, your guesses, the next test to run, and the check that proves the fix. A coding agent acts on the facts you give it. When a fact is missing, it guesses, and a guess written as a fact sends it to the wrong file. The template is free and works with any tool, or with none.

Page owner: Jaco Veldsman, hi@bugtape.ai. Last checked 26 October 2026. I build BugTape. The Jam, Sentry and Chrome DevTools facts on this page come from their own docs, read on 26 October 2026 and linked where they are used.

Facts table

Section	What goes in it	Why your agent needs it
Steps	What the user clicked and typed, in order	The agent can reproduce the path in a test
Actual and expected	What happened, and what should have happened	The agent knows what the fix must change
Environment	Browser, OS, release or commit, URL	The agent looks at the code that was live
Evidence you have	Console errors, failed requests with status, stack trace, replay link	The agent starts from the line that failed
Evidence you are missing	Each thing you could not get	The agent does not invent it
Guesses	Your theories, each one marked as a guess	The agent tests them before it acts on them
Next test	One check that would confirm or rule out the top guess	The agent runs it before it edits code
Acceptance check	What must be true before you merge	The agent knows when it is done, and so do you

The template

Copy this block into a new file or straight into your agent's chat. Delete any line you cannot fill, and list it under "Evidence I am missing" instead.

# Bug: <one line: what broke, where>

## Steps the user took
1. 
2. 
3. 

## What happened
<exact error text or behaviour; quote messages word for word>

## What I expected
<the correct behaviour>

## Environment
- Browser and version:
- OS:
- Release or commit:
- URL (remove tokens and personal data):
- Signed in as: <role or test account; never a real customer's details>
- First seen / how often:

## Evidence I have
- Console errors:
- Failed requests (method, URL, status, time taken):
- Stack trace (file and line):
- Replay or recording link:

## Evidence I am missing
- <for example: no server log for this request>
- <for example: could not reproduce on my machine>

## My guesses (not confirmed)
- GUESS: 
- GUESS: 

## Next test to run
<one test, command or check that would confirm or rule out the first guess>

## Acceptance check
- [ ] The steps above no longer fail
- [ ] A test covers this case and fails without the fix
- [ ] No new console errors or failed requests on this page
- [ ] A person reviews the pull request before merge

## Instructions for the agent
Read the evidence first. Do not treat anything under "My guesses" as fact.
Run the next test before you change code. If you need evidence that is
missing, ask for it. Do not guess it.

Why each section matters to an agent

Steps give the agent a path to follow in a test. Without them, it reads the code and imagines how a user could reach the failure.

What happened and what you expected sit apart on purpose. "Checkout is broken" tells the agent nothing it can check. "The Pay button shows a spinner that does not stop" and "the order confirmation page should load" tell it what to change.

Environment points the agent at the right code. A bug in last week's release may already be fixed on your main branch. The release or commit lets the agent compare the two.

Evidence you have is where the agent starts. A failed request with its status code, or a stack trace with a file and a line, saves it from reading the whole codebase.

Evidence you are missing is the section most reports leave out. When you say plainly that you have no server log, the agent knows the server side is unknown. When you say nothing, it may assume the server is fine.

Guesses are useful, but only when they are labelled. Mark each one with GUESS so the agent tests it before it builds a fix.

The next test keeps the agent from editing code before it knows the cause. One failing test that reproduces the bug is the best start for a fix.

The acceptance check tells you and the agent when the work is finished. Keep a person reviewing every pull request.

A filled-in example

This is an illustrative example. The shop, the code paths and the error are made up to show the format. They do not describe a real customer or a real incident.

# Bug: Pay button spins forever on checkout for some users

## Steps the user took
1. Added one item to the cart
2. Opened /checkout and entered a shipping address
3. Pressed Pay

## What happened
The Pay button showed a spinner that did not stop. No error message
appeared. The order was not created.

## What I expected
The order confirmation page loads, or an error message explains what failed.

## Environment
- Browser and version: Chrome 130 (from the request's user agent)
- OS: macOS
- Release or commit: web@a1b2c3d
- URL: https://shop.example.com/checkout
- Signed in as: guest checkout
- First seen / how often: after the a1b2c3d release; I saw it twice in testing

## Evidence I have
- Console errors: TypeError: Cannot read properties of undefined (reading 'id')
- Failed requests: POST /api/orders returned 500 after 1.2 s
- Stack trace: src/checkout/submitOrder.ts line 48
- Replay or recording link: <link>

## Evidence I am missing
- The server log for the failed POST /api/orders
- Whether signed-in users hit the same failure

## My guesses (not confirmed)
- GUESS: the API returns an error body with no order object, and
  submitOrder.ts reads order.id without a check
- GUESS: the spinner never stops because the catch block does not reset it

## Next test to run
Write a unit test for submitOrder that mocks a 500 response from
/api/orders, and check whether it throws the same TypeError.

## Acceptance check
- [ ] A 500 from /api/orders shows an error message and stops the spinner
- [ ] The new test fails before the fix and passes after it
- [ ] Guest and signed-in checkout both still create orders
- [ ] A person reviews the pull request before merge

## Instructions for the agent
Read the evidence first. Do not treat anything under "My guesses" as fact.
Run the next test before you change code. If you need evidence that is
missing, ask for it. Do not guess it.

How to fill it in

By hand, from browser DevTools. Open DevTools and repeat the steps. Copy the red lines from the Console panel. In the Network panel, find the failed request and note its method, status and time. Chrome's Network panel can copy a single request as cURL or as fetch, or save every request as a HAR file. Chrome's default HAR export is sanitized and leaves out the Cookie, Set-Cookie and Authorization headers (Chrome DevTools network reference, checked 26 Oct 2026). Remove tokens and personal data before you paste anything into a chat.

From Jam. Jam keeps the available logs, network requests, user events and device details with each recording (jam.dev, checked 26 Oct 2026). Its MCP server at https://mcp.jam.dev/mcp lets an agent read a Jam's console logs, network requests and user events (Jam MCP docs, checked 26 Oct 2026). Use those to fill "Steps" and "Evidence I have". Someone has to record the Jam first. In the browser, that is the Jam extension.

From Sentry. A Sentry issue page shows the stack trace, breadcrumbs (a timeline of activity before the error, such as HTTP requests and console logs) and tags such as the browser, device or user (Sentry issue details docs, checked 26 Oct 2026). Sentry's MCP server at https://mcp.sentry.dev/mcp connects agents such as Claude Code and Cursor to Sentry for searching errors and triaging issues (Sentry MCP, checked 26 Oct 2026).

Automatically, with BugTape. BugTape's browser capture records uncaught errors, failed requests and requests that hang, and groups repeats into one issue. Your agent calls get_repro_context over MCP and gets the report text, a timeline, the failed request, the console and the stack for one report. That fills "Evidence I have" without copying. BugTape's replay is rebuilt from DOM events. It does not record screen video. Screenshots and voice notes in the report form are not available yet. Server SDKs send errors with no replay or console. The Swift SDK captures handled errors and breadcrumbs only, with no fatal crash capture. You still write the guesses, the next test and the acceptance check yourself.

Before you start

Treat any text that came from a user session as untrusted input for your agent. A console message or a request body can hold text that looks like an instruction. Keep the "Instructions for the agent" lines in the template, and keep a person reviewing every pull request.

FAQ

What should a bug report include?

Steps to reproduce, what happened, what you expected, the environment, and the evidence. For a coding agent, also list what evidence is missing, mark your guesses as guesses, and say how you will check the fix.

Do I need BugTape to use this template?

No. The template is plain markdown. You can fill it in by hand from browser DevTools, or from any tool that records errors or sessions.

Why mark guesses separately?

An agent treats the text you give it as true. If a guess reads like a fact, the agent may write a fix for a cause that is not real. A GUESS label tells it to test the idea first.

Can I paste the whole template into Claude Code, Cursor or Codex?

Yes. Paste it into the chat, or save it as a file in your repository and point the agent at the file. Remove tokens, cookies and personal data first.

What if I cannot reproduce the bug?

Say so under "Evidence I am missing". Make the next test a way to collect the missing evidence, such as a log line around the code that failed. Do not ask the agent for a fix before you have that evidence.

Can my agent fill in the template for me?

It can fill in the parts it can read. With BugTape connected over MCP, the agent can read the request, console, stack and timeline for a report. The read-only demo MCP at https://app.bugtape.ai/demo/mcp needs no account. On Free and Prepaid credits each agent read of a bug costs 2 credits; reads are free on Pro.