gh-yebot-rad-cc-plugins-plugins-github-project-manager/commands/gh-project-triage.md

name, description, tools, model

name	description	tools	model
gh-project-triage	Triage project items and ensure proper status and priority assignment	Bash, AskUserQuestion, TodoWrite	inherit

Triage GitHub Project Items

This command facilitates systematic triage of project items, ensuring all items have proper priority, status, and other critical field assignments.

Instructions

Step 1: Initialize Triage Session

Ask the user what scope of triage they want:

1. Full Triage: Review all items in the project
2. Backlog Only: Focus on Backlog status items
3. Unprioritized: Only items missing priority
4. New Items: Items added in last N days
5. Custom Filter: User-specified criteria

Step 2: Gather Project Data

# Get project info
PROJECT_DATA=$(gh project view <number> --owner "@me" --format json)
PROJECT_ID=$(echo $PROJECT_DATA | jq -r '.id')
PROJECT_TITLE=$(echo $PROJECT_DATA | jq -r '.title')

# Get fields and options
FIELDS=$(gh project field-list <number> --owner "@me" --format json)

# Extract field IDs
STATUS_FIELD=$(echo $FIELDS | jq -r '.[] | select(.name=="Status") | .id')
PRIORITY_FIELD=$(echo $FIELDS | jq -r '.[] | select(.name=="Priority") | .id')

# Get field options
STATUS_OPTIONS=$(echo $FIELDS | jq -r '.[] | select(.name=="Status") | .options[] | {name: .name, id: .id}')
PRIORITY_OPTIONS=$(echo $FIELDS | jq -r '.[] | select(.name=="Priority") | .options[] | {name: .name, id: .id}')

# Get all items
ITEMS=$(gh project item-list <number> --owner "@me" --format json --limit 100)

Step 3: Filter Items Based on Triage Scope

# Example: Unprioritized items
TRIAGE_ITEMS=$(echo $ITEMS | jq -r '
  .items[] |
  select(
    (.fieldValues[] | select(.name=="Priority")) == null
  ) |
  {
    id: .id,
    title: .content.title,
    number: .content.number,
    type: .content.type,
    url: .content.url,
    body: .content.body,
    labels: .content.labels,
    status: (.fieldValues[] | select(.name=="Status") | .name)
  }
')

TRIAGE_COUNT=$(echo $TRIAGE_ITEMS | jq -s 'length')

Step 4: Present Triage Summary

Show user what needs triage:

## Triage Summary

**Project**: [Project Title] (#[Number])
**Scope**: [Triage scope selected]
**Items to Triage**: [Count]

### Breakdown
- Unprioritized: [X]
- Without status: [Y]
- Missing estimation: [Z] (if applicable)
- No assignee: [A] (if applicable)

**Proceeding with triage...**

Step 5: Interactive Triage Loop

For each item requiring triage:

A. Present Item Details

---
## Item [current]/[total]

**Title**: [Item title]
**Number**: #[number] (or "draft")
**Type**: [Issue/PR/Draft]
**Current Status**: [Status or "Not set"]
**Current Priority**: [Priority or "Not set"]
**URL**: [URL if available]

### Description
[First 200 chars of body...]

### Labels
[List issue labels if any]

### Context Hints
[Analyze title/description for priority hints:]
- Contains "critical", "blocking", "urgent" → Suggests P0/P1
- Contains "bug", "error", "broken" → Suggests P1/P2
- Contains "enhancement", "feature" → Suggests P2/P3
- Contains "nice-to-have", "someday" → Suggests P3

B. Assess Priority

Use intelligent priority suggestion:

# Auto-suggest priority based on keywords
TITLE_LOWER=$(echo "$ITEM_TITLE" | tr '[:upper:]' '[:lower:]')
BODY_LOWER=$(echo "$ITEM_BODY" | tr '[:upper:]' '[:lower:]')
COMBINED="$TITLE_LOWER $BODY_LOWER"

if echo "$COMBINED" | grep -qE "critical|blocking|urgent|security|production down|data loss"; then
  SUGGESTED_PRIORITY="P0"
  REASON="Critical keywords detected (blocking, security, urgent)"
elif echo "$COMBINED" | grep -qE "bug|error|broken|failing|regression"; then
  SUGGESTED_PRIORITY="P1"
  REASON="Bug-related keywords detected"
elif echo "$COMBINED" | grep -qE "enhancement|feature|improve"; then
  SUGGESTED_PRIORITY="P2"
  REASON="Enhancement/feature keywords detected"
else
  SUGGESTED_PRIORITY="P3"
  REASON="Standard priority (no high-urgency indicators)"
fi

# Check issue labels for additional hints
if echo "$LABELS" | grep -qE "critical|p0"; then
  SUGGESTED_PRIORITY="P0"
  REASON="Critical label found"
elif echo "$LABELS" | grep -qE "bug|urgent|p1"; then
  SUGGESTED_PRIORITY="P1"
  REASON="Bug/urgent label found"
fi

Present suggestion and ask for confirmation:

### Suggested Priority: [P0/P1/P2/P3]
**Reasoning**: [Reason based on analysis]

**Priority Criteria**:
- **P0 (Critical)**: Blocking issues, security vulnerabilities, data loss, production outages
- **P1 (High)**: Important bugs, features affecting many users, time-sensitive work
- **P2 (Medium)**: Standard enhancements, non-blocking bugs, improvements
- **P3 (Low)**: Nice-to-have features, minor improvements, future work

**Select Priority**: [P0/P1/P2/P3/Skip]

C. Assess Status

If status is not set or needs review:

### Current Status: [Status or "Not set"]

**Recommended Status**:
- **Backlog**: Not yet refined or scheduled
- **Todo**: Refined and ready to start
- **In Progress**: Actively being worked on
- **In Review**: PR open, awaiting review
- **Done**: Completed and merged/deployed

**Select Status**: [Backlog/Todo/In Progress/In Review/Done/Skip]

D. Update Item

Apply the selected field values:

# Update priority
if [ "$SELECTED_PRIORITY" != "Skip" ]; then
  PRIORITY_OPTION_ID=$(echo $PRIORITY_OPTIONS | jq -r ". | select(.name==\"$SELECTED_PRIORITY\") | .id")

  gh project item-edit --id $ITEM_ID --project-id $PROJECT_ID \
    --field-id $PRIORITY_FIELD \
    --single-select-option-id $PRIORITY_OPTION_ID

  echo "✅ Updated priority to $SELECTED_PRIORITY"
fi

# Update status
if [ "$SELECTED_STATUS" != "Skip" ]; then
  STATUS_OPTION_ID=$(echo $STATUS_OPTIONS | jq -r ". | select(.name==\"$SELECTED_STATUS\") | .id")

  gh project item-edit --id $ITEM_ID --project-id $PROJECT_ID \
    --field-id $STATUS_FIELD \
    --single-select-option-id $STATUS_OPTION_ID

  echo "✅ Updated status to $SELECTED_STATUS"
fi

E. Ask About Additional Fields

If project has other important fields:

### Additional Fields (Optional)

- **Story Points**: [1/2/3/5/8/13/Skip]
- **Component**: [Frontend/Backend/DevOps/Skip]
- **Assignee**: [@username or Skip]
- **Sprint/Iteration**: [Current/Next/Later/Skip]

**Skip all additional fields?** [Yes/No]

Step 6: Batch Mode (Alternative)

For experienced users or bulk triage, offer batch mode:

## Batch Triage Mode

Applying automatic prioritization based on keywords and labels...

[For each item:]
- #[number] [title]
  → Priority: P[X] (reason: [reason])
  → Status: [Status]

**Preview [X] changes. Proceed?** [Yes/No/Review individually]

Step 7: Generate Triage Report

After completing triage:

# Triage Session Complete

**Project**: [Project Title]
**Duration**: [Start time - End time]
**Items Processed**: [Count]

---

## Summary of Changes

### Priority Assignment
- P0 (Critical): [X] items
- P1 (High): [Y] items
- P2 (Medium): [Z] items
- P3 (Low): [A] items
- Skipped: [B] items

### Status Assignment
- Backlog: [X] items
- Todo: [Y] items
- In Progress: [Z] items
- Skipped: [A] items

### Field Updates Total
- [X] items updated
- [Y] items skipped
- [Z] items had errors

---

## Items Still Requiring Attention

[If any items were skipped or errored:]
- #[number] [title] - [Reason for skip/error]

---

## Project Health After Triage

**Priority Coverage**: [X]% of items now have priority
**Status Coverage**: [Y]% of items have appropriate status
**Recommendations**:
[Provide 2-3 recommendations based on triage results]

---

## Next Steps

1. **Review P0/P1 items**: Ensure critical items are scheduled
2. **Sprint planning**: Move refined items from Backlog to Todo
3. **Assign work**: Distribute items to team members
4. **Regular triage**: Schedule weekly triage sessions

**View updated project**: [Project URL]

Triage Best Practices

Priority Assessment Guidelines

P0 Criteria (Critical - Immediate attention):

• Production is down or severely degraded
• Data loss or corruption risk
• Security vulnerability
• Blocking all users from core functionality
• Legal or compliance risk

P1 Criteria (High - This week):

• Significant user impact (>25% of users)
• Important feature broken
• High-value customer request
• Sprint commitment
• Dependency for other work

P2 Criteria (Medium - This month):

• Moderate user impact
• Standard feature request
• Improvement to existing feature
• Non-blocking bug
• Technical debt with visible impact

P3 Criteria (Low - Backlog):

• Nice-to-have feature
• Minor cosmetic issue
• Optimization without user impact
• Long-term improvements
• Ideas for future exploration

Status Assessment Guidelines

When to use Backlog:

• Item needs more information
• Not yet refined or estimated
• Awaiting dependencies
• Future work, not committed

When to use Todo:

• Fully refined and ready to start
• Acceptance criteria defined
• No blockers
• Can be pulled into current sprint

When to use In Progress:

• Work has actively started
• Assignee is working on it
• PR may or may not exist yet

When to use In Review:

• PR is open
• Awaiting code review
• Testing in progress
• Documentation pending

When to use Done:

• Code merged
• Tests passing
• Deployed to production (if applicable)
• Acceptance criteria met

Automation Suggestions

After triage, suggest automation rules:

### Recommended Automation

Based on this triage session, consider setting up:

1. **Auto-priority for labeled issues**:
   - Issues with "critical" label → P0
   - Issues with "bug" label → P1
   - Issues with "enhancement" label → P2

2. **Auto-status from PR state**:
   - When PR opens → Move to "In Review"
   - When PR merges → Move to "Done"

3. **Auto-archive**:
   - Items in "Done" for >30 days → Archive

4. **Notifications**:
   - Alert on new P0 items
   - Daily digest of P1 items in Backlog

[Link to automation setup guide]

Important Notes

• Context Matters: Item priority depends on project goals and current sprint
• Team Alignment: Ensure team agrees on priority definitions
• Regular Cadence: Weekly triage prevents backlog chaos
• Don't Over-Triage: It's okay to leave P3 items rough until needed
• Save Time: Use batch mode for obvious cases, interactive for complex items
• Document Decisions: Add comments to items explaining priority rationale

Definition of Done

• Triage scope determined
• Items fetched and filtered
• Each item assessed for priority
• Each item assessed for status
• Field values updated successfully
• Changes verified
• Triage report generated
• Remaining items noted
• Next steps provided
• Automation suggestions offered

Error Handling

• If item update fails: Log error, continue to next item, report at end
• If field options missing: Alert user, skip that field for affected items
• If user cancels mid-triage: Save progress, provide partial report
• If API rate limit: Pause, wait, resume from last item

Remember: Good triage is the foundation of effective project management. Taking time to properly prioritize and organize items saves hours of confusion and misprioritized work later.