What is bug-triage used for?

To triage and convert bug reports into well-structured GitHub issues with severity and area labels, ready for filing and assignment.

What if the bug cannot be reproduced?

Flag the issue as needs-repro, request additional information, and avoid filing until reproduction steps are confirmed.

How are owners assigned?

Assign if the suspected cause clearly points to a specific owner; otherwise leave unassigned for a triage meeting.

bug-triage

Scanned

npx machina-cli add skill zakelfassi/skills-driven-development/bug-triage --openclaw

Files (1)

SKILL.md

2.7 KB

Bug Triage

Convert a bug report (user message, error log, Sentry alert) into a well-structured GitHub issue.

Inputs

Bug report (raw text, screenshot, error log, or Sentry URL)
Reporter (who reported it, if known)
Environment (production, staging, local)

Steps

Reproduce or verify
- Can you reproduce the bug from the report?
- If yes: document exact reproduction steps
- If no: flag as "needs-repro" and note what you tried

Classify severity

Severity	Criteria	Label
P0	Data loss, security, or full outage	`severity:critical`
P1	Major feature broken, no workaround	`severity:high`
P2	Feature broken, workaround exists	`severity:medium`
P3	Minor annoyance, cosmetic	`severity:low`

Identify the component
- Frontend / Backend / Infrastructure / Extension
- Add the corresponding label: area:frontend, area:backend, etc.

Write the GitHub issue

## Bug: [one-line description]

**Severity:** P[0-3]
**Environment:** [production/staging/local]
**Reporter:** [name or "internal"]

### What happened
[Clear description of the bug]

### Expected behavior
[What should have happened]

### Reproduction steps
1. ...
2. ...
3. ...

### Evidence
[Error logs, screenshots, Sentry link]

### Suspected cause
[If you have a hypothesis, state it]

File the issue

gh issue create --title "Bug: [description]" --body "[body]" --label "bug,severity:[level],area:[component]"

Assign if obvious
- If the suspected cause points to a clear owner, assign them
- If not, leave unassigned (triage meeting will handle it)

Conventions

Bug titles always start with Bug:
Every bug issue has both a severity: and area: label
P0 bugs get a Slack notification (via scripts/notify-critical.sh)
Duplicate bugs are closed with a reference to the original

Edge Cases

Vague reports: Ask the reporter for reproduction steps before filing. Don't file issues you can't act on.
Already fixed: Check recent commits/PRs. If fixed, reply to reporter and don't file.
Feature request disguised as bug: Re-label as enhancement and move to backlog.

Source

git clone https://github.com/zakelfassi/skills-driven-development/blob/main/examples/webapp-starter/skills/bug-triage/SKILL.md

View on GitHub

Overview

Bug triage converts reports into structured GitHub issues with severity, reproduction steps, environment, and ownership. It standardizes input from user messages, logs, or Sentry and speeds up resolution. This reduces guesswork and ensures consistent labeling and assignment.

How This Skill Works

The process starts by reproducing or verifying the bug from the report, then classifies severity and identifies the affected component. Next, it crafts a GitHub issue using the prescribed template, applies severity and area labels, files the issue via gh, and assigns an owner if obvious.

When to Use It

A bug report arrives (user message, log, or Sentry link) that needs triage.
Error logs or alerts require reproduction steps and validation before fixing.
You need a structured, labeled GitHub issue to begin work quickly.
The suspected cause points to a clear owner for assignment.
You’re preparing issues for a triage meeting or backlog planning.

Quick Start

Step 1: Gather bug report details, reporter, and environment; try to reproduce or mark as needs-repro.
Step 2: Classify severity and identify the component to label (area:...).
Step 3: Write the issue using the template, attach evidence, file via gh, and assign if obvious.

Best Practices

Verify reproduction: reproduce or flag as needs-repro and note attempts if reproduction isn’t possible.
Classify severity using the defined scale (P0–P3) and add area labels (frontend, backend, etc.).
Include evidence: logs, screenshots, and Sentry links to support the issue.
Draft the GitHub issue with the provided template and accurate environment details.
Check for duplicates and assign an owner if a clear handoff is identified.

Example Use Cases

Production outage: users cannot log in; severity: critical; area: backend; evidence includes error stack and user reports.
Staging checkout flow fails with 500 errors; severity: high; area: backend; reproduction steps and Sentry link included.
Frontend profile image upload intermittently fails; severity: medium; area: frontend; workaround exists.
Settings page shows minor typography misalignment in local environment; severity: low; area: frontend.
Duplicate bug report referencing the same N+1 query in search; triage notes original issue for reference.

Frequently Asked Questions

Add this skill to your agents