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

Related

• Skill: gh-issue-templates

• Creating well-formatted issues

• Skill: gh-issue-lifecycle

• State transitions and linking

• Agent: gh-wrangler

• Interactive triage workflow