Issue Triage

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

Quick Reference

Label Taxonomy

Type Labels (mutually exclusive)

Priority Labels (mutually exclusive)

Status Labels (mutually exclusive)

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

1. Issue created using gh-issue-templates (gets needs-triage label)
2. Use gh-issue-triage (this skill) to determine type and priority
3. Apply labels using gh-wrangler agent
4. 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

Related

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