triage-issue

Triaging a GitHub Issue

Overview

Triage = assign type/ + priority/ labels, leave a key comment when there's judgment worth recording, then remove status/needs-triage. Inspect the repo's label schema via gh label list — the type/* / priority/* / status/* convention used below is a common default but adapt to what the repo actually has.

Scope: one issue per invocation. For backlog walkthroughs, the caller enumerates gh issue list --label status/needs-triage and invokes this skill per result.

Core principle: comments are signal, not ceremony. Skip when the issue body already covers what you'd say. Only add information the reader can't get from the body or labels alone.

When to Use

• User says "triage #N" / "triage this issue"
• An issue lacks type/ or priority/ labels
• An issue carries status/needs-triage

For backlog work (triage backlog / many issues at once), the caller orchestrates: list issues, invoke this skill per issue.

Process

1. Read the issue: gh issue view <n>
2. Read body before deciding (title alone misses scope)
3. Decide labels: type/ + priority/
4. Decide comment: see Comment Criteria below
5. Apply:

   gh issue edit <n> \
     --add-label type/X --add-label priority/Y \
     --remove-label status/needs-triage
   gh issue comment <n> --body-file -  # stdin, multi-line safe

Priority Rubric

Anchor: who is affected, how reversible the damage is, blast radius. If unsure between two tiers, downgrade.

Comment Criteria

Always comment when any of these apply:

• priority/critical or priority/high — record the call so it's defensible later
• Issue overlaps another (see also #N / dup of #N / subset of #N / blocks #N)
• Scope estimate is non-obvious (XS / S / M / L, or hours/days)
• A blocker exists (blocked by #N or requires upstream X)

Skip the comment when:

• Title + body already cover priority justification AND there's no cross-reference / scope / blocker to add
• Comment would just restate what's in the body

Don't repeat the body. If the author already explained why this is critical, the triage comment is for meta information: relationships, scope, dates, defensibility.

Don't read code during triage. If you find an issue needs claims verified against actual code, root cause confirmed, or blast radius probed — that's investigation. Switch to the investigate-issue skill and do that one issue properly. Half-investigation makes comments worse than light triage.

Comment Template

Mirrors the repo's PR template style — emoji-headed sections for at-a-glance scanning. Sections that add nothing get omitted (don't write "N/A" headers; just skip).

## 🏷️ Triage YYYY-MM-DD
 
`type/X` · `priority/Y` · effort: **S/M/L**
 
### 📊 At a Glance
 
<diagram (mermaid or ascii) + 1-line caption — only include when there's something visual worth showing>
 
Use a diagram when:
 
- Cluster fix order: `#29 → #30 → #25` (ascii arrows OK)
- Attack flow / race condition: mermaid `sequenceDiagram`
- Before/after refactor: mermaid `flowchart` or ascii box
 
Skip the section entirely (don't write empty header) when labels + Related list already convey the picture — most simple triages won't need it.
 
### 🔗 Related
 
- <only if relevant: dup of / blocks / blocked by / see also #N>
 
### 🚧 Notes
 
<only if priority justification missing from body, or scope is non-obvious>

Language: match the issue body. Keep label values, command names, and section headings (At a Glance, Related, Notes) as-is.

Sizing: XS = <1h · S = half-day · M = 1–3d · L = >3d. Estimate from blast radius, not from line count.

Section budget:

• 🏷️ Triage line + 📊 At a Glance — always include (this is the load-bearing summary)
• 🔗 Related — include when there's a real cross-link, otherwise drop the heading
• 🚧 Notes — include only when body lacks priority justification or scope is non-obvious; otherwise drop the heading

Don't restate what the body already says. The triage comment is meta-information about the call, not a re-summary of the issue.

Quick Reference

Common Mistakes

• Repeating the body in the comment — adds noise. The body is already there; comment for meta only.
• Commenting on every issue — silence on a clear medium/low is correct.
• priority/critical for "important but not drop-everything" — reserve critical for true emergencies. Default to high when in doubt.
• Forgetting --remove-label status/needs-triage — leaves the issue stuck in backlog filter forever.
• Date drift — always use today's date in the comment header so future you knows when the call was made.