QA Triage

QA Triage

Turn a QA report into a triaged decision and, where warranted, one or more well-formed technical issues — without resolving the report off the bat or writing any app code.

QA reports (filed by a tester, usually carrying a qa label) are the tester's view of a problem. They describe user-visible symptoms; the engineering fix is often differently scoped — one report may need several tech issues, or several reports may share one root cause. This skill does the standard review-and-extrapolate ritual: read the report, confirm it against the codebase, decide what (if anything) to build, and draft the issue(s) — then stop for the human to approve before anything is created.

Where it sits in the workflow. This is the first step for a qa-labeled issue. Its output feeds the normal pipeline: an approved tech issue goes to /resolve-issue → /create-pr → /walkthrough + /code-review → merge. This skill never implements; it only triages and drafts. When several qa reports accumulate, /qa-triage-batch fans this skill out across the whole queue and reconciles shared root causes across reports behind one consolidated gate — use it for a backlog; use this skill directly for a single report.

Applicability. Needs a GitHub repo (gh). Built around a QA-report labeling convention but otherwise project-agnostic — no project names, tester identities, or paths are hardcoded. It reads the project's CLAUDE.md for local conventions (board, workflow, bilingual i18n, etc.) and embeds the rest itself.

Not the same as:

• /resolve-issue — it implements an approved issue. This one creates the issue for it to implement. Hand off; don't duplicate.
• /qa-handoff, /walkthrough — those help a tester exercise the app and file reports. This one processes a report after it's filed.

The core guardrail

A QA report is an input, not a directive. It is taken seriously, but it is not gospel: a tester may misread intended behavior, or suggest a change that would be counterproductive. The product decision — whether and how to act, including on items framed as "fixes" — belongs to the human, worked through a separate tech issue. So this skill's job ends at a decision gate: it analyzes and proposes; the human decides. The only thing it ever routes straight to resolution — instead of into a drafted tech issue — is an explicit, approved trivial-cosmetic fix, and even that is handed to /resolve-issue; this skill never writes app code itself.

Your task

When passed more than one issue number, triage each in turn, presenting a full analysis and decision gate per report before moving to the next.

1. Fetch the report

• gh issue view <N> --json number,title,body,labels,author,comments,url — capture the symptom, steps, expected vs actual, locale, screenshots, and the author (needed later for the verification @-mention).
• Note whether it carries the qa label. If it clearly isn't a QA report, say so and confirm the user still wants to triage it.
• If the body references a Honeybadger fault, note it — the eventual fix should mark that fault Resolved (re-arms notifications).

2. Orient on project conventions

• Read the project's CLAUDE.md (and any QA-workflow notes it points to) for: whether the project uses a separate-tech-issue workflow, a project board, type-label taxonomy, bilingual/i18n requirements, and viewport/mobile rules. Adapt to what you find; default to the separate-tech-issue pattern for non-trivial work.
• Resolve the invoker once: gh api user --jq .login. You'll compare it to the report author for the @-mention.

3. Investigate against the codebase

• Search the code for the surface the report describes and confirm the symptom is real. Reproduce the logic path; find the root cause; note the file(s) involved.
• Distinguish what the tester saw from what the code actually does — this is where "not-a-bug" and "wrong-assumption" cases surface. State your evidence (e.g. "no validates :event_type exists on the model; the field is an unbacked string column").
• Weigh evidence of design intent before calling something a bug. Guards (if x.present?), defaults, the absence or presence of a validation, and existing tests reveal whether the current behavior was chosen. Code that consistently tolerates the reported state was most likely written to allow it — a strong signal the report is a feature ask or working-as-intended, not a regression.
• For UI/text reports, find the exact source (e.g. the i18n key) and check every affected locale, not just the one in the report.

4. Classify

Sort the report into exactly one bucket and recommend the matching action:

When unsure between buckets, surface the ambiguity at the gate rather than guessing — especially the "is this even intended behavior?" question, which is the human's to answer.

5. Draft the proposal

For every tech issue you'd create, draft it in full (don't create yet) using the Tech issue template below:

• Title: Conventional Commits prefix matching the work (feat:/fix:/chore:/docs:). This doubles as the type label so /resolve-issue can infer the branch prefix.
• Acceptance criteria: a - [ ] checklist /resolve-issue can check off. Include "mark the Honeybadger fault Resolved after deploy" when applicable.
• Back-link: a Triggered by QA report #<qa> line. ("Triggered by" is deliberately a non-keyword verb — it creates a reference, never an auto-close.)
• Closing plan: how the eventual PR should close things (see @-mention logic and multi-PR rule below).
• Labels: the type label, plus any the project's taxonomy calls for. Do not add the qa label to tech issues — that label belongs to reports.