Triage a Bug Report

Triage decides what a report is, how bad it is, whether it is new, and who acts next, quickly and the same way every time. A triaged issue has a title that says what breaks, steps anyone can follow to see it, a severity and priority from the rubric, the area and owner it belongs to, and a reply to the reporter. Fixing is a separate job.

When to use

• A new issue, support escalation, crash alert or error-tracker event arrives.
• "Can you go through the bug backlog?", "is this a duplicate?", "how bad is this?"
• A customer report forwarded by a teammate in the support team.

What you need

• The issue tracker: the owner's GitHub, GitLab, Linear or Jira connected app (Connections page), or the tracker open in your browser where the owner signed in. If neither is available, ask the owner with clarify or work from exported issues they send.
• The team's triage rules, saved in memory after you ask the owner once (see the table below).
• A place to reproduce: the current release or main on your computer, a staging environment, or the app in your browser with a test account.

What you may do on your own

Action	Default until the owner says otherwise
Add labels, link duplicates, rewrite titles, add triage notes	Yes
Comment on issues in the team's own tracker	Yes, factual and short
Assign an issue to a person	Suggest only
Close duplicates or stale needs-info issues	Propose a list; the owner or a maintainer closes
Reply to an external reporter or customer	Draft only; the owner or support teammate sends
Make an issue private, post anything about security	Owner only

Method

1. Read everything. The full report, comments, attachments and linked tickets.

   • Screenshots and recordings: vision_analyze. Logs and traces: read_file.
   • Extract: expected behaviour, actual behaviour, steps, version or commit, environment (OS, browser, device, plan, region, account), when it started, how often, who is affected, any workaround.

2. Classify the type.

   • Bug: documented or previously working behaviour is broken.
   • Regression: it worked in an earlier version (note which).
   • Feature request, question or support issue, configuration or user error: relabel and route, do not reproduce.
   • Security issue: step 3.

3. Security reports skip the queue. Anything suggesting data exposure, authentication bypass, injection or account takeover:

   • do not discuss details in public comments;
   • do not try to exploit it beyond what the report shows;
   • tell the owner immediately through a private channel and ask whether to make the issue private.

4. Check for duplicates. Search open and closed issues by the error message, the component, distinctive words and the affected endpoint or screen.

   • A closed match may mean a regression: link it and say so.
   • A duplicate: link the two, keep the one with the best reproduction open, copy any new facts across.

5. Reproduce on the current version. Follow the steps exactly in a clean environment, then minimise them by removing one step at a time. Record where it does and does not reproduce. Use test accounts or staging, never real customer accounts unless the owner has allowed it.

   • Reproduced: write the minimal steps.
   • Not reproduced: try the reporter's environment (browser, version, data shape, locale, time zone). Still nothing: label it needs-info and ask targeted questions using references/triage-templates.md. Never close as "cannot reproduce" on the first pass.

6. Rate severity and priority with references/severity-rubric.md. Severity is impact (how bad when it happens); priority is urgency (when to fix).

   • Data loss, security or money handled wrongly is S1 however few users are hit.
   • A regression in a released version raises priority one step.
   • Unsure between two levels: pick the higher and write why.

7. Locate the likely area, and stop there.

   • search_files in the code for the error message or the screen's text.
   • git log --oneline -10 -- <path> for recent changes in that file.
   • CODEOWNERS or the team's area map for the owner. One or two sentences like "probably in src/billing/invoice.ts, changed in commit abc123 two days ago" save the fixer an hour.

8. Write the issue up. Title pattern: ": when ". Body from references/triage-templates.md. Labels for type, severity, priority and area. Suggest or assign the owner per the rules above.

9. Reply to the reporter. Confirm what you reproduced or what you need, say what happens next without promising dates, give the workaround if there is one. Post or hand over the draft according to the autonomy table.

10. Escalate S1 and P0 at once. Tell the owner and the area owner directly (brief_team or ask_teammate for colleagues, plus the owner's usual channel). If users are being hurt right now, this is an incident, not a ticket.

11. Sweeping a backlog.

    • Put the issues on a todo list, oldest untriaged first.
    • For stale needs-info issues (no reply in the agreed time, often 14 days), propose a closing list rather than closing.
    • Finish with a show_card: counts by severity and type, the top five by priority, duplicates linked, issues waiting on reporters.
    • For recurring triage, offer to schedule the sweep with cronjob.

Worked example

Report: "Checkout broken!!! My discount doesn't work." After triage:

• Title: "Checkout: coupon discount ignored when the cart contains a gift card"
• Type: regression (worked in 3.8.0, fails in 3.9.0). Severity S2 (customers overcharged at checkout, workaround exists: remove the gift card and buy it separately). Priority P1 (S2 default, raised for regression, lowered for workaround).
• Minimal steps: add any product and a gift card, apply coupon TEST10, total shows no discount.
• Likely area: src/checkout/discounts.ts, changed in a1b2c3d (gift card support).

Output

For each issue: the rewritten title, type, severity and priority with a one-line reason, minimal reproduction steps (or the questions sent), the environment, duplicates linked, likely area and owner, labels applied, and the reply posted or drafted. For a sweep, the summary card from step 11.

Checks before you finish

• Each triaged issue has steps someone else can follow, or a needs-info label with specific questions asked.
• Severity and priority come from the rubric with a stated reason.
• Duplicates were searched in open and closed issues.
• No security detail was posted publicly.
• Nothing was closed, assigned or sent to a customer beyond what the owner's rules allow.

Pitfalls

• Rating by volume of complaint. One angry report about a cosmetic glitch is still S4; one quiet report of wrong invoices is S1.
• "Cannot reproduce" too early. Most non-reproductions are environment differences. Ask before closing.
• Fixing during triage. Triage is breadth. Note the likely cause and move on; a backlog left untriaged while you fix one bug is a worse outcome.
• Vague titles. "Bug in checkout" helps nobody searching later. Say what breaks and when.
• Losing the reporter's facts. When rewriting, keep their exact error text, IDs and timestamps.
• Promising dates. You do not own the roadmap. Say what happens next, not when it ships.
• Using real customer data casually. Reproduce with test data; redact personal data in issue text and screenshots.