What is a bug report? Definition and structure
A bug report is the written artifact that turns a noticed defect into something an engineer or AI agent can act on — a description, repro steps, and the expected vs actual behavior.
A bug report is the written artifact that turns a noticed defect into something an engineer or AI agent can act on — a description of the problem, the steps to reproduce it, and the gap between expected and actual behavior.
The format exists because finding a bug and fixing a bug usually involve different people, often hours or days apart. Without a deliberate handoff artifact, the fix relies on the reporter's memory at the moment the engineer asks, and most of the context is already gone.
The shape of a useful bug report
The non-negotiable fields are: a clear title, a description, repro steps, expected behavior, actual behavior, and the environment (browser, OS, account state, URL). Severity and priority go on top once a triager has looked at it.
The optional fields earn their keep: a screenshot or screencast removes the ambiguity in any visual defect, a console or network log makes intermittent bugs reproducible, and a link to the running build lets the engineer verify the regression without rebuilding the environment. For AI-agent-driven fixes the same fields apply, but the format that travels best is markdown with the screenshot inline and the source URL on a line of its own.
Frequently asked questions
What's the minimum a bug report needs?
A description of what went wrong, the steps to reproduce it, what was expected to happen, and what actually happened. Anything less and the engineer ends up doing investigation work the reporter already did.
Where should bug reports live?
In an issue tracker (Linear, Jira, GitHub Issues), not in chat. Chat is fine for the initial signal; the canonical record needs a stable URL the team can reference and the build can link to.
Capture your first review.
About a minute from open tab to a shareable URL your agent can ingest.
Start capturing