---
name: bug-report-quality
source: https://app.decimal.ai/s/bug-report-quality@1/SKILL.md
source_sha256: 492fdd2b3e0d
---

> **Template skill.** The severity and priority scales below are a worked example. Fork this
> skill and drop in your team's real labels and definitions — the agent then fills *your* fields.
> The structure (separate severity from priority, minimal numbered repro, refuse un-reproducible
> reports) is the part that carries the lift.

# Bug Report Quality

Turn a raw complaint into a defect report someone can act on without asking you a single follow-up
question. Left alone, models will happily accept "the checkout is broken" and start guessing at a
fix, and they collapse *severity* and *priority* into one vague "this is important" field. Both
habits waste engineering time. A fileable report has a fixed set of parts, and a report with no way
to reproduce the bug is not filed — it is sent back.

## A fileable report has these parts

Every part is required. If you cannot supply one from what you were given, that is a signal the
report is not ready (see *Refusing un-reproducible reports* below), not a field to leave blank or
invent.

1. **Title** — one line: what breaks, where. "Export button does nothing on the Reports page,"
   not "export bug."
2. **Environment / build** — the version or build number, and the platform it happened on
   (OS + browser, or app version + device). A bug that only reproduces on one build is a different
   bug; without this the report is not reproducible by anyone else.
3. **Steps to reproduce** — a **numbered** list, starting from a known state (logged in as X, on
   page Y), containing only the steps actually needed to trigger the bug (see *Minimal repro*).
4. **Expected result** — what should have happened, stated on its own.
5. **Actual result** — what happened instead, stated on its own. Include the exact error text,
   status code, or screenshot reference if there is one. "Expected vs actual" is two separate
   statements, not one sentence that implies both.
6. **Severity** — how bad the failure is *when it hits* (a technical/user-impact judgment).
7. **Priority** — *when it gets fixed* relative to other work (a scheduling/business judgment).

## Severity and priority are two different axes

This is the distinction models most often flatten. **Severity is about impact; priority is about
order-of-work.** They are set independently, and they routinely disagree.

- **Severity** answers: if this bug fires, how much damage? Data loss and crashes are high
  severity; a cosmetic misalignment is low — regardless of how many people hit it.
- **Priority** answers: should we fix this before or after the other open bugs? A bug on the
  signup page for every new user is high priority; the same-severity bug on a feature nobody uses
  is low priority.

Because they answer different questions, **a bug can be high on one axis and low on the other.**
Set each one on its own; never copy severity into priority.

| Situation | Severity | Priority | Why they diverge |
|---|---|---|---|
| App crashes when exporting a report — but only in a rarely-used admin CSV export, ~1 internal user/month | **High** (crash, data not produced) | **Low** (tiny blast radius, workaround exists) | Bad failure, but almost nobody hits it |
| Company name is misspelled in the headline of the public homepage | **Low** (cosmetic, nothing malfunctions) | **High** (every visitor sees it, brand damage) | Trivial defect, maximum visibility |
| Payment fails silently at checkout for all users | **High** | **High** | Both axes agree — but you still state both |

### Example scales (fork and replace)

*Severity — impact if it fires:*

| | Meaning |
|---|---|
| **S1 Critical** | Crash, data loss/corruption, security hole, or a core flow fully blocked with no workaround |
| **S2 Major** | A feature is broken or gives wrong results, but a workaround exists |
| **S3 Minor** | Works, but wrong/awkward behavior; limited impact |
| **S4 Trivial** | Cosmetic — typo, alignment, wording |

*Priority — when to fix, relative to other work:*

| | Meaning |
|---|---|
| **P1 Now** | Drop other work; fix before next release |
| **P2 Next** | Scheduled into the current cycle |
| **P3 Later** | Backlog; fix when convenient |
| **P4 Someday** | Nice-to-have; may never be scheduled |

## Minimal repro

Steps to reproduce should be the **shortest** sequence that still triggers the bug, starting from a
defined state. Strip everything incidental:

- If the reporter clicked through five screens to get there but the bug reproduces from step three
  onward, start at step three.
- Remove steps that don't change the outcome (logging out and back in, unrelated navigation).
- Each step is one concrete action, in order, with the specific input used ("enter `-1` in the
  Quantity field," not "enter a bad value").
- If the bug is intermittent, say so and state how often ("~1 in 5 attempts"), rather than
  presenting flaky steps as deterministic.

A reader should be able to follow the numbered steps top to bottom and land on the actual result.

## Refusing un-reproducible reports

**Do not file — and do not start debugging — a report you cannot reproduce.** "It's broken," "it
doesn't work," "the app is slow," or "checkout failed" with no steps, no expected/actual, and no
build is not a defect report; it is a starting point for questions.

When a report is missing what's needed to reproduce it, **push back and ask for the specific missing
pieces** instead of accepting it or guessing at a root cause. A report is not fileable without, at
minimum:

- a way to reproduce it (steps, or a reliable trigger), **and**
- what was expected vs what actually happened, **and**
- the build/version and platform it happened on.

Ask only for what's actually missing, and be specific about it — request the exact steps, the build
number, the device/OS — rather than replying "please add more detail." Guessing a cause from a
one-line complaint is exactly the failure this skill exists to prevent.

## Worked example

**Input (what you were handed):**

> "Hey, the reports thing is busted. I tried to download my numbers and it just spun forever and
> then nothing. Really annoying, can you get this fixed?"

**Correct response:** this can't be filed yet — there's no build, no environment, and no
reproducible sequence. Ask for the missing pieces, then, once given "Build 4.2.1, Chrome on
Windows 11, logged in as a Viewer, click Reports → pick last month → click Export CSV → spinner
never resolves; expected a downloaded file," produce:

```
Title: Export CSV on Reports page hangs forever, no file downloaded

Environment / build:
  App build 4.2.1 · Chrome 121 · Windows 11 · role: Viewer

Steps to reproduce:
  1. Log in as a Viewer.
  2. Open the Reports page.
  3. Set the date range to "Last month."
  4. Click "Export CSV."

Expected result:
  A CSV file of the selected report downloads within a few seconds.

Actual result:
  The export spinner appears and never resolves; no file is downloaded and no error is shown.
  (Reproduces every attempt.)

Severity: S2 Major — a documented feature fails, but the data is still viewable on-screen (workaround).
Priority: P2 Next — affects any Viewer trying to export, but not a crash or data-loss path.
```

Note the two judgments are set independently: **S2** describes how bad the failure is; **P2**
describes when it should be scheduled. Neither was copied from the other.

## Checklist

A good defect report:

- [ ] Has a one-line title naming what breaks and where
- [ ] Records the build/version and the platform (OS/browser or app/device)
- [ ] Lists reproduction steps as a numbered, minimal sequence from a known state
- [ ] States expected and actual results as two separate items
- [ ] Assigns a severity (impact) and a priority (fix-order) as **two independent** fields
- [ ] Sends back — rather than files or debugs — any report with no way to reproduce it