bug-report-template

Overview

A well-formed bug report is the input contract for triage, repro, and fix. Industry consensus from Mozilla's long-standing bug-writing guide (mozilla-bug-writing) and the ISO/IEC/IEEE 29119-3:2021 incident-report format converges on the same eight fields:

Terminology note: ISTQB distinguishes error (human action), defect / fault / bug (imperfection in a work product), and failure (deviation from delivered service). This skill uses "bug" and "defect" interchangeably with "fault" reserved for the code-level imperfection. Reports describe failures and the reporter's hypothesis about the underlying defect.

The skill is a workflow that takes raw input (a chat message, a voice memo transcription, a copy-pasted error) and produces a filled template - refusing to leave any required field blank.

When to use

• A stakeholder describes a problem informally and wants it tracked.
• The team is migrating triage to a structured tracker (Linear, Jira, GitHub Issues) and needs a per-template template.
• A support ticket lacks the structure engineering needs.
• You're preparing a postmortem for an incident-tier bug and need a clean baseline report to anchor the timeline.

If the team already has a working bug template in their tracker, this skill is not for replacing it - it's for filling it correctly. Adapt the field set below to the team's existing template.

How to use

1. Extract verbatim errors, the UI surface, environment details, and the reporter's expected-vs-actual from the raw input (Step 1); flag any gap instead of fabricating.
2. Draft a Summary under 60 chars that names the surface and the observable behavior, not the fix (Step 2).
3. Write numbered, deterministic, self-contained Steps to Reproduce, quantifying the rate for intermittent bugs (Step 3).
4. State Expected and Actual separately, pasting the verbatim error or a screenshot for Actual (Step 4).
5. Score Severity and Priority independently, then Reproducibility (Steps 5-6).
6. Assemble the fields into the Output format template, leaving [GAP] markers on any field the reporter did not supply.

Step 1 - Extract raw evidence

From the input (chat message, error log, screenshot caption, voice memo), extract:

• Verbatim error messages (with quotation marks).
• The exact UI surface (URL or screen name) where the issue was observed.
• Any environmental details the reporter mentioned (OS, browser, app version).
• What the reporter expected vs. what they observed - separately. Often the reporter conflates these; tease them apart.

If any of these is missing, flag the gap rather than fabricating; the gap is a triage signal in itself.

Step 2 - Draft the Summary

Per Mozilla's guidance, summaries should be under 60 characters and describe the problem, not the solution (mozilla-bug-writing).

A good summary names the surface (URL/screen) and the observable behavior (what's wrong).

Step 3 - Build the Steps to Reproduce

Per mozilla-bug-writing, reproduction steps must be:

• Numbered in execution order.
• Specific - exact buttons, exact URLs, exact input values.
• Deterministic - no "around step 5 it sometimes...".
• Self-contained - start from a known state (logged out, fresh browser session).

Example contrasting good vs. bad:

Bad:
1. Go to the site and try to check out.

Good:
1. Open https://example.com/ in Firefox 128 (private window).
2. Click "Add to cart" on the first product card.
3. Click the cart icon (top right).
4. Click "Checkout".
5. Leave the shipping address fields empty.
6. Click "Place order".

If the bug is intermittent, document the reproduction rate ("8 out of 20 attempts on macOS Sonoma 14.4 / Firefox 128") - quantify the rate, don't guess.

Step 4 - Separate Expected from Actual

Mozilla's example pattern (mozilla-bug-writing):

Expected: My Inbox displays correctly.
Actual:   The page shows "Your browser does not support cookies
          (error -91)".

Reject blurry phrasings like "it doesn't work" or "page displays incorrectly" - they push the cost of investigation onto the engineer instead of the reporter.

For UI bugs, attach a screenshot as the Actual body. For backend bugs, paste the exact error message + status code. If a stack trace is available, capture it verbatim as input for hypothesis extraction.

Step 5 - Pick Severity (intrinsic) and Priority (extrinsic)

Score two independent fields: Severity (what the defect does to the user when it manifests) and Priority (when the team plans to fix it relative to other work). They are not the same axis - a Critical-severity bug for a non-paying user can be P2, and a Minor-severity bug on the marketing homepage can be P0 the day before launch. Score severity from impact; let the PM / engineering decide priority from business context.

Use the classification scales in references/severity-and-priority-scales.md.

Step 6 - Score Reproducibility

Per mozilla-bug-writing:

• Always - every attempt reproduces.
• Sometimes - quantify the rate (12/20, ~30%).
• Once - observed once; cannot reproduce despite trying.
• Unable - reporter could not reproduce after the initial sighting.

A Once or Unable bug is not a candidate for fix-then-close - it's a candidate for adding monitoring or extending the test suite to catch it next time.

Output format

## <Summary, <60 chars, problem-not-solution>

**Severity:** Critical | Major | Moderate | Minor
**Priority:** P0 | P1 | P2 | P3
**Reproducibility:** Always | Sometimes (X/Y) | Once | Unable

### Environment

- **App / Build:** <name + version + commit SHA if known>
- **OS:** <macOS 14.4 / Windows 11 23H2 / Ubuntu 24.04 / iOS 18.0>
- **Browser / Runtime:** <Firefox 128 / Chrome 130 / Node 22.5.0 / Python 3.12>
- **Locale / Timezone:** <en-US / UTC+0> (only when relevant)
- **Device / Viewport:** <iPhone 13 / 1280x800 desktop> (only when relevant)

### Steps to reproduce

1. <step>
2. <step>
3. ...

### Expected

<one sentence - what should have happened>

### Actual

<verbatim error / observed behavior; attach screenshot or log>

### Notes

<optional: any context the reporter mentioned that doesn't fit elsewhere - recent changes, why they were doing this, what they tried>

Worked example - from a Slack message

Input:

"hey, the checkout flow is broken on mobile - i hit the place order button and nothing happens. tried twice. firefox on my phone."

The skill identifies missing fields and produces a draft with gap flags for the missing data:

## Place order button does nothing on mobile checkout

**Severity:** Major (feature unusable; needs reporter confirmation)
**Priority:** P1 (until severity is confirmed)
**Reproducibility:** Sometimes (2 attempts confirmed by reporter)

### Environment

- **App / Build:** [GAP - confirm the build / version]
- **OS:** [GAP - "my phone" - confirm iOS or Android + version]
- **Browser:** Firefox (mobile)
- **Locale / Timezone:** [GAP - only if business-logic-relevant]
- **Device:** [GAP - confirm phone model]

### Steps to reproduce

1. [GAP - confirm starting URL or screen]
2. Add a product to the cart.
3. Navigate to checkout.
4. Tap "Place order".
5. Observe: nothing happens.

### Expected

Tapping "Place order" submits the order and navigates to the
confirmation screen.

### Actual

Tapping "Place order" produces no visible response (no nav, no error,
no spinner).

### Notes

Reporter tried twice. Returning to reporter for the gaps before triage.

The [GAP] markers force the reporter to fill them in, rather than the engineer triaging on incomplete data.

Variant - from a stack-trace dump. Given an automated alert with the full production stack trace, the skill drafts the report with Steps to Reproduce marked Unable - production crash (no manual repro yet) and the Actual field populated with the verbatim trace, flagged for hypothesis extraction.

Anti-patterns

References

• references/severity-and-priority-scales.md - the Severity and Priority classification scales used in Step 5.
• mozilla-bug-writing - Mozilla's bug-writing guide; practitioner-emergent canonical for summary / steps / expected / actual structure.
• ISO/IEC/IEEE 29119-3:2021 - incident-report content (cite by stable standard ID; spec is paywalled at iso.org).