Bug Report Generator

A good bug report is a reproduction, not a complaint

The difference between a bug that gets fixed today and one that sits open for a month is almost never the difficulty of the fix. It is the quality of the report. 'The login is broken' is a complaint - it tells the developer nothing about where to look, what to type, or how to know when it is fixed. A real bug report is a reproduction: it hands the developer the exact sequence that triggers the failure, states what should have happened, and states what actually happened instead. If they can reproduce it, they can almost always fix it.

This generator captures the seven fields that make a bug reproducible - a specific title, severity, environment, numbered steps, expected behavior, actual behavior, and logs - and emits clean Markdown ready to paste into any issue tracker. It also flags which fields are still missing, because the most common failure of a bug report is not being wrong, it is being incomplete.

The anatomy of a reproducible report

• Title - specific enough to be useful in a list of fifty. 'Reset email never arrives for Gmail' beats 'email bug'.
• Severity - how much it hurts and how urgent it is, so triage can rank it against everything else.
• Environment - version, OS, browser, account type, region. Half of hard bugs only reproduce in one environment.
• Steps to reproduce - numbered, exact, starting from a known state. This is the single most important field.
• Expected behavior - what should have happened, so there is no argument about whether it is even a bug.
• Actual behavior - what actually happened, described precisely, including what did work as a contrast.
• Logs - the error output, stack trace, or console messages that point at the failure.

Reproduction steps are where reports live or die

A developer cannot fix what they cannot reproduce, so the steps field carries more weight than all the others combined. Good steps start from a known state ('a fresh incognito window, logged out'), list one action per line, and are specific about inputs ('enter a @gmail.com address that already has an account', not 'enter an email'). The test of a good repro is simple: could a developer who has never seen the bug follow your steps and watch it happen? If any step requires knowledge you have not written down, the repro is incomplete and the bug will bounce back to you with 'cannot reproduce'.

Environment is where the hard bugs hide

The bugs that eat days are the ones that only happen in one environment - one browser version, one operating system, one region, one account tier, one screen size. When the environment is missing from the report, the developer tests on their own machine, cannot reproduce it, and closes the issue. Then it comes back. Capturing the environment up front short-circuits that whole loop. If you do not know which environment detail matters, list everything you can - version, OS, browser, device, network, account type - and let the developer narrow it down.

Severity is a triage signal, not a feeling

Severity exists so the team can rank a new bug against everything already in the queue. Anchor it to impact, not frustration: critical means data loss, an outage, or a security hole and should stop other work; high means a core flow is broken with no reasonable workaround; medium means it is broken but there is a way around it; low means cosmetic or minor. Honest severity keeps trust in the system - if everything is filed as critical, nothing is, and real emergencies get lost in the noise.

Handing the bug report to Claude Code

A well-structured bug report is close to the ideal prompt for Claude Code, because it already contains everything the model needs to start debugging: the exact reproduction, the expected and actual behavior, the environment, and the error output. Paste the report in and ask it to form a hypothesis about the root cause before touching any code. The numbered steps let it trace the code path; the expected-versus-actual gap tells it precisely what to explain; and the logs often point straight at the failing line. A vague report forces the model to guess; a structured one lets it reason.

1. Paste the report and ask 'What is your top hypothesis for the root cause, and what would confirm or rule it out?'
2. Give it the relevant files and ask it to trace the reproduction steps through the code path.
3. Have it propose the smallest fix that closes the expected-versus-actual gap, plus a test that would have caught the bug.
4. Confirm the fix against the original steps to reproduce - the bug is only closed when those steps no longer trigger it.

Anti-patterns this tool prevents

• The one-liner - 'it's broken' with no steps, no environment, and no expected behavior.
• The essay - three paragraphs of narrative where seven labeled fields would be instantly scannable.
• The missing repro - a description of the symptom with no way to trigger it, guaranteeing a 'cannot reproduce' bounce.
• Everything is critical - severity inflation that destroys the team's ability to triage.
• No logs - the error output was right there in the console and never made it into the report.