---
name: bug-report
description: Write bug reports a developer can act on without a single follow-up question. Use whenever you are asked to write, rewrite, or review a bug report, file an issue, or turn a vague "it's broken" message into a ticket.
---

# Bug report skill

When the user describes a defect — in any form, however vague — produce a bug report in the format below. Ask for missing reproduction details only if they cannot be inferred; never pad fields with guesses.

## The format

```
Title: [What broke] on [where], when [action]

Environment
- URL / screen:
- Browser + version:
- Operating system:
- Device / screen size:
- User account or role:

Steps to reproduce
1.
2.
3.

Expected result
What should have happened.

Actual result
What happened instead.

Evidence
- Screenshot / recording:
- Console errors:
- Network errors:

Impact
- Who is affected:
- Is there a workaround:

Severity: Blocker / Critical / Major / Minor / Trivial
```

## Rules

1. **Title is a sentence, not a label.** "Checkout broken" is a label. "Checkout fails with 500 on Safari 17 when applying a discount code" is a title. Pattern: what broke, where, doing what.
2. **Steps start from a known state.** "Logged in as a Team user, on an empty cart" — not "from wherever I was". Number them. Include the exact data used (the specific file size, the specific code): bugs live in data as often as in flows.
3. **If it is intermittent, say how often.** "Roughly one in five attempts" is useful. "Sometimes" is not.
4. **Expected and actual are separate fields.** A surprising share of reported bugs are mismatched expectations; splitting the two surfaces that cheaply.
5. **Evidence beats description.** A console line replaces a paragraph. If evidence is missing, say so explicitly rather than describing around it.
6. **Impact is the reporter's to state, severity is a guess.** Always fill "who is affected" and "workaround" — they decide urgency more than the severity label does.
7. **Severity ≠ priority.** Severity is how badly it breaks (technical). Priority is how soon it gets fixed (business). Only set severity; leave priority to triage.
8. **No filler.** Omit an optional field rather than writing "N/A" prose. Never invent environment details.

## Example

**Input:** "the upload thing doesn't work for big pdfs, nothing happens"

**Output:**

```
Title: PDF upload fails silently over 10 MB on Chrome 141 / Windows 11

Environment
- URL / screen: Project Settings → Attachments
- Browser + version: Chrome 141
- Operating system: Windows 11
- User account or role: Team user

Steps to reproduce
1. Log in as a Team user
2. Open Project Settings → Attachments
3. Upload a 12 MB PDF
4. Click Save

Expected result
File uploads and appears in the attachment list.

Actual result
Progress bar reaches 100%, dialog closes, no file appears. No error shown.

Evidence
- Console errors: POST /api/attachments 413 (Payload Too Large)

Impact
- Who is affected: any user attaching design files
- Is there a workaround: yes — split the PDF

Severity: Major
```

## Where this came from

The full guide, with per-tool variants (Jira, GitHub, Excel, Sheets, Word, Markdown) and the reasoning behind each field: https://userback.io/guide/bug-report-template/