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.

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"). The e2e-flake-bisector agent works the same way - 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, the crash-stack-trace-analyzer takes the trace as input.

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

Per ISO/IEC/IEEE 29119-3:2021 (incident-report content; cite by stable standard ID - the spec is paywalled but the field semantics are widely adopted):

Severity describes what the defect does to the user when it manifests. Independent of business prioritization:

Priority describes when the team plans to fix:

The two are independent: a Critical-severity bug for one user might be P2 if the user is non-paying; a Minor-severity bug on the marketing homepage might be P0 if launch is tomorrow.

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>

Examples

Example 1: 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.

Example 2: from a stack trace dump

Input: an automated alert with the full stack trace from production.

The skill drafts the report with Steps to Reproduce marked Unable — production crash (no manual repro yet), the Actual field populated with the verbatim trace, and a recommended hand-off to the crash-stack-trace-analyzer agent to extract a hypothesis.

Anti-patterns

References

• 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).
• bug-repro-builder - agent that turns a filled template into a minimal failing test.
• crash-stack-trace-analyzer - agent that extracts hypothesis from a stack-trace-only input.