Guide · Updated July 2026
Bug Report Template Your Agent Can Act On
You came for a bug report template. Here it is — copy it, it's the classic for a reason. Then stay for the part most template pages won't tell you: if the bug is in your own app and an AI coding agent is doing the fixing, the best bug report in 2026 isn't a form at all. It's a marked-up screenshot your agent can act on, plus three lines of context.
Both formats below are copyable. Which one you need depends on who's reading the report — a stranger who has to triage it, or an agent that already holds your whole codebase.
The classic template
Title: [one line — what broke, where: "Checkout button
unresponsive on cart screen"]
Environment:
- App version / build:
- Device and OS:
- Account / state: [logged in? empty data? first run?]
Steps to reproduce:
1.
2.
3.
Expected result:
[what should have happened]
Actual result:
[what happened instead — include exact error text]
Evidence:
[screenshot or recording — mark the broken element]
Severity: [blocks users / embarrassing / cosmetic]
What each field is actually for
The classic template was designed for handoffs between strangers: user to support, support to triage, triage to whichever dev picks up the ticket. Every field earns its place in that pipeline:
| Field | Who needs it | Why |
|---|---|---|
| Title | Triage | Makes the report findable and dedupable in a tracker |
| Environment | Whoever debugs it | Half of mobile bugs are device-, OS-, or state-specific |
| Steps to reproduce | Whoever fixes it | A bug you can't reproduce is a bug you can't verify as fixed |
| Expected vs actual | Whoever fixes it | The delta is the bug — without "expected," a report is just a complaint |
| Evidence | Everyone downstream | The screenshot settles what prose never will |
| Severity | Whoever prioritizes | Breaks-users outranks cosmetic, every time |
If you're filing into someone else's project — an open source repo, a vendor's tracker — use the classic template and fill in everything. Maintainers triage reports from strangers, and incomplete reports get closed, not fixed.
What changed in 2026
Now look at who's actually reading your bug reports. If you're a solo dev building with Claude Code, Codex, or Cursor, there's no support queue and no assigned dev. The "engineer picking up the ticket" is an agent that already holds your entire codebase, reads images natively, and starts work the moment you hand it context.
That collapses most of the form:
| Classic field | Does your agent need it? |
|---|---|
| Title | No — it isn't searching a tracker |
| Environment | Sometimes — device and OS still matter for rendering and platform bugs |
| Steps to reproduce | Yes — still the spine of reproduction and verification |
| Expected vs actual | Yes — but a circle and an arrow often say both faster |
| Evidence | It became the report — a marked-up screenshot carries element, screen, state, and layout at once |
| Severity | No — you decide priority; the agent doesn't triage |
Which is the subversion this page promised: the best bug report in 2026 is a marked-up screenshot your agent can act on. The screenshot does the pointing — no "no, the OTHER red box," no paragraph of spatial prose. Words are reserved for the two things pixels can't say: what triggered the state, and what you expected instead. The full case for showing over telling is in show your coding agent what's wrong.
The agent-ready template
Attach the screenshot, broken element circled, and paste this with it:
[Attached: screenshot — the broken element is circled]
Bug: [one sentence — "circled label overflows its card on long
names"]
Trigger: [action or state that produced it — "profile screen,
display name over ~20 characters"]
Expected: [one sentence — what this should look like or do]
Error text, if any: [verbatim]
Environment, if it matters: [device / OS / app version]
Fix this one issue only. No refactors, no restyling of nearby
elements, no silent rewrites. Then tell me:
1. What you changed, and why that was the cause.
2. Exact steps to verify the fix on this screen.
The closing instructions are load-bearing. Agents restructure code around the thing you asked for, and an unscoped "fix this" on a small bug is how a working screen turns into a vibe coded mess. The verification demand matters just as much — your agent never sees the fixed screen, it ships blind, so make it hand you the checking instructions instead of a bare "done."
Which template, when
| Situation | Use |
|---|---|
| A user or tester is reporting to you | Classic — they don't have your codebase; you need their environment and steps |
| Filing to open source or a vendor | Classic, every field — strangers triage it |
| You found it in your own app; your agent fixes it | Agent-ready — marked-up screenshot plus trigger and expectation |
| Visual bug that's hard to put into words | Skip the words almost entirely — circle it |
One more honest note on the genre: report-perfecting tools exist — Jam turns browser sessions into immaculate tickets, and the AI bug reporting field keeps polishing the artifact. But the report was never the goal. The fix is. For your own mobile app, Vibejar collapses the template entirely: capture the bug inside your iOS or Android app, circle it, and the report assembles itself — screenshot, markup, context — lands with your agent, and comes back as a shipped fix with before/after proof. $88, one time. The workflow it slots into is the screenshot-to-fix loop; the wider practice is vibe debugging; and if your reporters are users rather than you, start with why users don't report bugs.
Frequently asked questions
What should a bug report include?
The durable core is four things: how to reproduce it, what you expected, what actually happened, and evidence — ideally a screenshot with the broken element marked. Environment (device, OS, version) matters for mobile and platform-specific bugs. Title and severity exist for trackers and triage; skip them when there's no tracker in the loop.
How is a bug report for an AI agent different?
Shorter, and visual-first. The agent already has your codebase, so you drop the tracker fields and lead with a marked-up screenshot — it carries the element, screen, and state in one artifact. You add the trigger and the expected result in a line each, then two guardrails: fix only this issue, and report back exact verification steps.
Do steps to reproduce still matter with agents?
Yes — they're the field that survives every format change. An agent can find code from a screenshot, but reproduction is how a fix gets verified, by you or by it. If you can't spell out the steps, capture the state instead: what screen, what data, what you tapped last. Unstated state is where "can't reproduce" bugs hide.
What makes a bug report actionable?
Precision about the target and the delta. The fixer must know exactly which element or behavior is wrong (a circle on a screenshot is the strongest pointer there is) and exactly what correct looks like. Add reproduction steps and verbatim error text, and a competent fixer — human or agent — can act on the first pass without a clarifying round trip.