# Bug Report

> Draft a structured, reproducible bug report from a failure description, error log, stack trace, screenshot, or observed unexpected behavior. Always use this skill when asked to file a bug, write a defect, report an issue, or when the user pastes an error/log/screenshot and describes something not working as expected — even without the word "bug" (e.g. "this button doesn't do anything", "getting a 500 here", "this should say X but shows Y"). Do not use for feature requests or general questions about how something works.

- Skill: `santoshhundekar-qa/bug-report` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add santoshhundekar-qa/bug-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/santoshhundekar-qa/bug-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: santoshhundekar-qa (https://skillmd.com/u/santoshhundekar-qa)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/santoshhundekar-qa/bug-report

---


# Bug Report

Turns a raw observation (log, screenshot, description, stack trace) into a bug report a developer can act on without asking follow-up questions, in the team's tracker format (Jira/Qase defect).

## Process

1. **Separate fact from inference.** Only report what was actually observed (what happened, what was expected, what environment). Don't state a root cause unless it's explicitly confirmed — a guess presented as fact wastes a developer's time chasing the wrong thing.
2. **Reproduce, don't assume.** If steps to reproduce weren't given, ask for them rather than inventing plausible-sounding steps — a bug report with fabricated repro steps is often worse than no report, because it looks confirmed when it isn't.
3. **Classify severity and priority separately** — severity is about technical/business impact (data loss, crash, security > major function broken > minor/cosmetic), priority is about urgency to fix. They don't always match (a rare crash can be high severity, low priority if it barely occurs).
4. **Check for duplicates conceptually** — if the user's description strongly resembles a known recurring issue pattern in the project (ask if unsure), flag that possibility rather than filing a near-duplicate silently.
5. **Attach evidence inline** — reference the log line, error code, or screenshot description directly in the report body so nothing gets lost between the chat and the tracker.

## Output format

ALWAYS use this structure:

```
Title: [Component/Area] — concise description of the failure, not the fix
Environment: [Platform, browser/app version, OS, user role — whatever is known; mark "not provided" rather than guessing]
Preconditions: [State before the bug occurs]
Steps to Reproduce:
  1. ...
  2. ...
Expected Result: [What should have happened]
Actual Result: [What actually happened — exact error text/code if available]
Severity: [Critical / Major / Minor / Cosmetic]
Priority: [High / Medium / Low]
Frequency: [Always / Intermittent / Once — mark "unknown" if not stated]
Evidence: [Log excerpt, error code, or screenshot description]
Additional Notes: [Anything relevant that doesn't fit above — workarounds observed, related tickets]
```

See `references/severity-priority-guide.md` for the classification rubric and `references/examples.md` for two worked examples.

## What not to do
- Don't state a root cause or "likely fix" unless it's already confirmed by the person reporting — flag it as a hypothesis if you must mention it at all, clearly separated from the facts.
- Don't invent steps to reproduce, environment details, or frequency — write "not provided" and ask if it's blocking.
- Don't downgrade severity to make a report look less urgent, or upgrade it to force attention — classify based on the rubric, not on how the user feels about the bug.