Guides · Bugs and AI coding agents

Bug report template for AI coding agents

Updated Sep 23, 2026

A bug report an agent can act on lists what you did, what the app sent back, and what threw, in the order it happened: timestamped clicks, failed requests with method, status and response body, and console errors with their stack. Copy the template below, or let Roll write it for you as timeline.md.

The template

# <One line: what broke, where>

**URL:** https://app.example.com/checkout
**Env:** production · Chrome 140 · macOS · 1440×900
**Account / state:** free plan, 2 items in cart, coupon applied
**Expected:** order confirmation page
**Actual:** spinner forever, no error shown

## Timeline (in order)
- t+00:00 · navigate /checkout
- t+00:04 · click "Place order"
- t+00:04 · POST /api/orders → 500 (1.8s)
- t+00:06 · console error: TypeError: Cannot read properties of undefined (reading 'id')

## Failed requests
### POST /api/orders → 500
request:  {"cartId":"c_123","coupon":"FALL10"}
response: {"error":"coupon.discount is undefined"}

## Console errors
TypeError: Cannot read properties of undefined (reading 'id')
    at OrderSummary (OrderSummary.tsx:88)
    at renderWithHooks (react-dom.development.js:...)

## Already tried
- Happens without the coupon too? No, only with FALL10.

Why each part is there

• Env and account state. Half of "works on my machine" is a feature flag, plan or data shape the agent doesn't know about.
• Expected vs actual. One line each. The agent needs to know what "fixed" looks like.
• Timeline. User actions, requests and errors interleaved. This is the part people leave out and the part that matters most.
• Failed requests with bodies. The response body usually names the cause outright. A status code alone doesn't.
• Console errors with stacks. The stack points at the file and line.
• Already tried. Saves the agent from repeating your first three ideas.

Where to get the pieces by hand

• Failed requests: DevTools → Network → right-click the request → Copy → Copy response, or export a HAR.
• Console errors: DevTools → Console → right-click → Save as. See saving console logs.
• Timeline: you, from memory. This is where hand-written reports usually go wrong.

Or skip writing it

Roll writes this file for you. Record the tab, reproduce the bug, stop, and every recording includes a timeline.md in the same shape: clicks, requests with bodies and console errors in time order, plus a Failed requests section. Your agent reads it through the local MCP server (Cursor, Claude Code), or you paste it into any chat. See a real one in the demo recording.