# Bug Report

> Write a clear, reproducible bug report that gets fixed fast. Use when asked to write a bug report, file a defect, report an issue, or turn 'it's broken' into an actionable ticket. Produces a structured report — a precise title, steps to reproduce, expected vs. actual, environment, severity/priority, and evidence — so a developer can reproduce and fix it without a back-and-forth.

- Skill: `mohitagw15856/bug-report` (Agent Skill)
- Install (CLI): `npx skillmds add mohitagw15856/bug-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mohitagw15856/bug-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Mohit Aggarwal (https://skillmd.com/u/mohitagw15856)
- Updated: 2026-09-07
- Page: https://skillmd.com/skills/mohitagw15856/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.