Bug Report with Repro Steps
"It's broken" is not a bug report. It is a mood. An agent handed a mood will guess at what you meant, fix something adjacent to the problem, and report success, and you will not find out it fixed the wrong thing until the real bug bites again.
A usable bug report has three properties. It is reproducible: numbered steps that take a stranger from a clean start to the wrong behavior, every time. It is specific: what you expected, what you got instead, quoted exactly, not paraphrased from memory. And it separates observation from theory: what happened goes in one section, what you suspect goes in another, clearly labeled, so the agent investigates your evidence instead of inheriting your assumptions.
Write the repro steps as if the reader has never seen your project, because functionally, a fresh agent session hasn't. If you cannot reproduce it reliably, say so and describe the pattern; an intermittent bug honestly labeled is workable, an intermittent bug reported as consistent burns hours.
# Bug: [one line — what breaks, where]
## Environment
- App / project: [name and version, or git commit hash]
- Where it happens: [local dev / staging / production URL]
- OS and browser (if relevant): [e.g., macOS 15, Safari 18]
- Data state that matters: [logged in as which role, how many records, etc.]
## Steps to reproduce
Start from: [clean state — e.g., fresh `git clone`, `pnpm install`, `pnpm dev`,
logged out, empty cart. Be exact. "Start from wherever" invalidates everything below.]
1. [First action. One action per step.]
2. [Second action. Include exact values typed, exact buttons clicked.]
3. [Continue until the wrong behavior appears.]
Reproduces: [every time / roughly N times out of 10 / only under condition X]
## Expected behavior
[What should have happened at the final step. One or two sentences.]
## Actual behavior
[What actually happened. Quote error messages EXACTLY — copy-paste, don't
paraphrase. Include the full stack trace or console output in the block below.]
```
[paste error output / stack trace / relevant log lines here]
```
## What I already tried
- [Attempt 1 and what it changed or didn't]
- [Attempt 2]
## Suspicions (clearly labeled as guesses)
[Optional. "I suspect X because Y." The agent should verify this before
building on it, and should say so if the evidence points elsewhere.]
## Scope for the fix
- Fix the root cause, not the symptom.
- Do not refactor unrelated code while you're in there.
- Add a test that fails before the fix and passes after it.
- If the root cause turns out to be different from my suspicion, explain
the actual cause before writing the fix.Adaptation notes:
- For an intermittent bug, add a section logging each occurrence with a timestamp and what was happening; patterns show up in the log that memory flattens out.
- For a visual bug, attach a screenshot and name the file in the report; "looks wrong" plus a picture beats three paragraphs of description.
- The "What I already tried" section is not optional in practice. Skipping it is how you pay for the same dead end twice.
- Pairs with the verification habit in §6.1: when the agent claims the fix works, run the repro steps yourself before you close anything.