bug-report

Bug Report Skill

A bug report is only useful if someone else can reproduce it. The best ones are precise: an exact title,

numbered steps, what you expected vs. what happened, and the environment it happened in. This skill turns a

vague "it's broken" into a ticket a developer can act on immediately — no clarifying round-trips.

Working from a brief

Given "the export button doesn't work", write the full report anyway — infer the likely repro steps,

expected behaviour, and environment, marking inferences (confirm). Keep facts (what was observed) separate

from guesses (likely cause). Never invent logs/errors; flag them to attach.

Required Inputs

Ask for these only if they aren't already provided (else infer and label):

• What's wrong — what you did, what happened, and what you expected instead.
• Steps to reproduce — the exact sequence (and whether it's consistent or intermittent).
• Environment — device, OS, browser/app version, account/role, and any relevant data state.
• Evidence — screenshots, a screen recording, console/network errors, logs, request IDs.

Output Format

Bug Report

• Title — a precise one-liner: what's broken + where + the key condition ("Export to CSV fails for >1,000 rows on Safari").
• Severity / Priority — impact (blocker/critical/major/minor) and how widespread, kept distinct from urgency.
• Environment — device/OS/browser+version, app/build version, account/role, region/data as relevant.
• Steps to reproduce — numbered, exact, starting from a known state; note frequency (always / ~X% / once).
• Expected result — what should happen.
• Actual result — what actually happens (the observable failure — error text, wrong value, crash).
• Evidence — screenshots/recording, console & network errors, logs, request/correlation IDs (listed/attached).
• Notes (optional) — a workaround, when it started/regressed, and any suspected cause clearly marked as a hypothesis, not fact.

Quality Checks

• [ ] The title is specific enough to identify the bug at a glance
• [ ] Steps reproduce from a known starting state and note frequency (consistent vs. intermittent)
• [ ] Expected vs. actual are both explicit and the actual is the observable failure
• [ ] Environment (versions, role, data) is captured — the usual reason a bug "can't be reproduced"
• [ ] Severity (impact) is separated from priority (urgency)
• [ ] Observed facts are kept separate from suspected cause; evidence is referenced

Anti-Patterns

• [ ] Do not write "doesn't work" — state the exact action, expectation, and observed failure
• [ ] Do not omit environment/version — it's the top reason bugs aren't reproducible
• [ ] Do not merge expected and actual into one sentence — keep them distinct
• [ ] Do not present a guessed cause as fact — label hypotheses
• [ ] Do not bundle several bugs in one report — one defect per ticket

Based On

Defect-reporting practice — reproducibility-first reports with precise titles, expected/actual separation, environment capture, and impact/urgency distinction.