Markdown bug reports your agent can act on
A bug report is only as useful as the format it lands in. Markdown bug reports survive the trip from human to AI agent intact.
This page is for anyone who files bugs that an AI coding agent is going to read next. It walks through why markdown is the right format, what an agent-readable bug report looks like, and how CobaltCapture produces one in under a minute. For the full pattern applied to specific tools, see the feedback for AI coding agents hub.
Why markdown is the right format for a bug report
Markdown is plain text. That sounds boring until you remember what plain text gets you: it renders inside Linear ticket bodies, GitHub issues, ChatGPT, Cursor's composer, Claude Code's terminal, and the readme of the repo itself. The same characters work everywhere.
Embedded image syntax is the part most other formats miss.  is a first-class part of the spec, which means screenshots travel with their captions instead of getting orphaned as attachments. A markdown bug report carries its evidence inline.
The deeper reason markdown wins is that the same artifact serves two readers. A human teammate skims the H1, looks at the screenshot, scans the repro steps. An AI agent parses the same document by structure, heading, image URL, code block, paragraphs, and reasons about each. One file. Two audiences. No second translation step.
The structure of an agent-readable bug report
Five fields, in this order, every time.
- H1, the bug as a single sentence. "Cart total resets to $0 when coupon is re-applied." If an agent reads only the title, it should already know what to look for.
- Source URL, the page where the bug lives.
Source: https://app.example.com/cart?id=abc123. This tells the agent which route, view, or template to open first. - Embedded screenshot,
pointing at a stable public PNG. Agents that can read images get visual context. Agents that can't still see the alt text and the URL. - Dictated repro as paragraphs, what you saw, in the order you saw it, in the voice you'd use to explain it to the dev sitting next to you. Include the version, the browser, the order of operations.
- Expected vs actual, two lines. "Expected: $40 (2 x $25 with 20% off). Actual: $0.00." This is the test the agent will write against.
Add browser + version metadata as a trailing line. Chrome 120 on macOS Sequoia is enough. The agent will use it to scope the fix.
Example bug report
# Cart total resets to $0 when coupon is re-applied
Source: https://app.example.com/cart?id=abc123
Cart total reads $0.00 when a product with WINTER applied has its
quantity changed. Reproduces on Chrome 120 on macOS Sequoia. Did not
reproduce on the previous build, so this is a post-1.4.2 regression.
Repro:
1. Add SKU 1234 to cart
2. Apply code WINTER
3. Change quantity from 1 to 2
Expected: $40.00 (2 x $25 with 20% off)
Actual: $0.00
Browser: Chrome 120 / macOS Sequoia 15.1
What the agent does with it
Hand that document to Cursor, Claude Code, or any agent that reads markdown. The agent parses the H1 as the bug summary. It reads the source URL and opens the matching route in your repo, probably routes/cart.py and templates/cart.html. It fetches the embedded screenshot and reasons about the visual state. It walks the numbered repro list as a test plan. It reads "Expected vs Actual" as the assertion it needs to make pass.
That's enough context to write a fix that touches the right files, against the right component, on the first attempt. Compare that to a Slack thread where the screenshot is one message, the URL is two messages up, and the repro steps are buried in a follow-up. The agent doesn't get to reconstruct context from scrollback. It gets one shot at the input you handed it. Markdown makes that shot count.
Compared to other bug-report formats
A Linear ticket is great for tracking work but lossy for capture. The screenshot lives as an attachment, the source URL is in a custom field, the repro is in the description. The agent has to stitch the parts back together.
A Jira ticket is heavier and more manual. The fields are configurable, the format is whatever your team enforced two years ago, and the screenshot is buried two clicks deep.
A Slack thread has no structure and no permanent record. The bug is the third message, the screenshot is the fifth, the version is in a reaction. By next week it's out of scrollback.
A screenshot-only drop is the most common format and the most useless one for an agent. The image is the evidence; the agent needs the URL, the repro, and the assertion to act.
CobaltCapture publishes the structured document directly. For the QA-side framing of the same pattern, see the bug report tool for AI-in-the-loop QA page.
Get started
CobaltCapture is free to try. Capture your first bug report, publish it, and paste the URL into your agent's next prompt.
Related
Capture your first review.
About a minute from open tab to a shareable URL your agent can ingest.
Start capturing