Issue Triage

Rules and workflows for categorizing, labeling, and prioritizing GitHub issues.

Quick Reference

Label Type	Purpose	Mutually Exclusive?
Type	What kind of issue	Yes
Priority	How urgent	Yes
Status	Current state	Yes
Area	Which component	No

Label Taxonomy

Type Labels (mutually exclusive)

Label	Description	Color
`bug`	Something is broken	`#d73a4a` (red)
`feature`	New functionality	`#a2eeef` (cyan)
`enhancement`	Improvement to existing feature	`#84b6eb` (blue)
`docs`	Documentation only	`#0075ca` (dark blue)
`chore`	Maintenance, deps, infra	`#fef2c0` (yellow)

Priority Labels (mutually exclusive)

Label	Description	Response
`priority: critical`	Drop everything, fix now	Immediate
`priority: high`	Next up after current work	This sprint
`priority: medium`	Normal backlog	Scheduled
`priority: low`	Nice to have, someday	Backlog

Status Labels (mutually exclusive)

Label	Description
`needs-triage`	New, not yet categorized
`needs-info`	Waiting for reporter clarification
`accepted`	Triaged and in backlog
`in-progress`	Someone is working on it
`blocked`	Can't proceed, waiting on something

Area Labels (project-specific, not exclusive)

Define based on your project structure:

area: api
area: cli
area: docs
area: ui
area: auth

Triage Workflow

Step 1: New Issues

Every new issue gets needs-triage label automatically (via GitHub Actions or manually).

Step 2: Initial Review

Is this a duplicate?
  YES → Close with "Duplicate of #N", link original
  NO  → Continue

Is this spam/invalid?
  YES → Close without label
  NO  → Continue

Is the issue clear enough to act on?
  YES → Continue to Step 3
  NO  → Add `needs-info`, comment asking for clarification

Step 3: Categorization

Apply type label:
  - Broken functionality → `bug`
  - New capability → `feature`
  - Improve existing → `enhancement`
  - Documentation → `docs`
  - Maintenance → `chore`

Apply area label(s):
  - Based on affected component
  - Can have multiple areas

Step 4: Prioritization

Apply priority:
  - Production down / security issue → `priority: critical`
  - Major impact, many users → `priority: high`
  - Normal request → `priority: medium`
  - Nice to have → `priority: low`

Step 5: Finalize

1. Remove `needs-triage`
2. Add `accepted`
3. Assign to milestone (if applicable)
4. Suggest assignee (if known)

Priority Guidelines

Critical

Production is down
Security vulnerability
Data loss occurring
Blocks all users

High

Major feature broken
Significant user impact
Blocks important workflow
Time-sensitive deadline

Medium

Normal bug reports
Feature requests
Improvements
Most issues land here

Low

Minor cosmetic issues
Edge case bugs
Nice-to-have features
"Someday" items

Common Patterns

Insufficient Information

Issue: "It doesn't work"
Action:
1. Add `needs-info`
2. Comment: "Can you provide steps to reproduce and your environment?"
3. Wait for response

Duplicate Detection

Issue: Similar to existing #123
Action:
1. Close issue
2. Comment: "Duplicate of #123"
3. Add any new context to #123

Critical Security Issue

Issue: Security vulnerability
Action:
1. Add `priority: critical`, `bug`
2. Assign immediately
3. Consider private discussion

Feature Without Acceptance Criteria

Issue: "Add dark mode"
Action:
1. Add `feature`, `needs-info`
2. Comment: "Great idea! Can you describe acceptance criteria?"

Reference Files

See references/ for:

label-taxonomy.md - Complete label reference with colors

Integration with Other Components

Typical Triage Workflow

Issue created using gh-issue-templates (gets needs-triage label)
Use gh-issue-triage (this skill) to determine type and priority
Apply labels using gh-wrangler agent
Track state changes using gh-issue-lifecycle

Label Setup

Use references/label-taxonomy.md to:

Create labels with correct colors: gh label create "bug" --color "d73a4a"
Maintain consistent taxonomy across repositories
Setup new repositories with standard labels

Priority Assignment

Consult "Priority Guidelines" section in this skill:

Critical: Production down, security, data loss
High: Major features broken, significant impact
Medium: Normal bugs and features (most issues)
Low: Nice-to-have, cosmetic, edge cases

Skill: gh-issue-templates - Creating well-formatted issues
Skill: gh-issue-lifecycle - State transitions and linking
Agent: gh-wrangler - Interactive triage workflow

gh-issue-triage