/triage-backlog

Triage Backlog

Incrementally groom the GitHub issue backlog for the current repo. Walks through untriaged issues one at a time, checking if work has been completed, updating task lists, and suggesting labels.

Arguments

• depth: quick, standard (default), or deep - controls how thoroughly to check if issues are completed
• batch size: defaults to 10 issues per session

Examples:

• /triage-backlog - standard depth, 10 issues
• /triage-backlog deep - deep analysis, 10 issues
• /triage-backlog quick 25 - quick scan, 25 issues
• /triage-backlog deep 5 - deep analysis, 5 issues

Depth	Behavior	Cost
quick	Check for linked PRs and obvious keyword matches in recent commits	Low
standard	Search git log --all with keywords from issue title/body	Medium
deep	Standard + grep codebase for features/fixes described in issue	Higher

Rules

• Never delete issues
• Always ask before editing - present recommendations, wait for approval
• Use gh CLI only - no GitHub MCP server
• Incremental - mark issues with "triaged" label after processing so you can work in stages across sessions

Workflow

Phase 1: Setup

1. Fetch all open issues:

   gh issue list --state open --json number,title,labels,body,createdAt,updatedAt --limit 500
   

2. Fetch existing repo labels:

   gh label list --json name,color,description
   

3. Ensure "triaged" label exists:

   gh label create "triaged" --description "Issue has been reviewed during backlog triage" --color "C5DEF5"
   

   (This succeeds whether the label exists or not)

4. Filter out issues already labeled "triaged"

5. Sort remaining issues oldest first (by created date) - the longest-forgotten issues are most likely to have been completed by overlapping work

6. Take the first N issues (batch size, default 10)

7. Report to user:

   Found X open issues. Y already triaged. Processing next Z (oldest first). W remaining after this batch.

   If all issues are triaged, offer to re-triage (remove "triaged" labels and start fresh).

Phase 2: Per-Issue Analysis

Process the batch one at a time. For each issue:

Step 1: Display Context

Show:

• Issue number + title
• Current labels
• Age (created date, last updated)
• Body summary (first ~200 chars)

Step 2: Check if Completed

Based on the depth argument:

Quick depth:

• Check if issue body/comments mention PRs or commits
• Check for linked PRs: gh pr list --state merged --search "closes #N OR fixes #N"

Standard depth (default):

• Everything in Quick, plus:
• Extract 3-5 keywords from title and body
• Search commit history: git log --all --oneline --grep="<keyword>" for each keyword
• If matches found, read relevant commits to assess if they resolve the issue

Deep depth:

• Everything in Standard, plus:
• Grep the codebase for features, functions, or fixes described in the issue
• Read relevant code to assess completion

Step 3: Check Task Lists

If the issue body contains task list items (- [ ] or - [x]):

• Parse each unchecked item
• At standard/deep depth: search for evidence each task was completed
• Propose checking off completed items

Step 4: Suggest Labels

Based on issue title and body, suggest labels from this topic set:

• Match against existing repo labels first
• Common topics: seo, testing, playwright, performance, bug, enhancement, documentation, accessibility, security, refactor, ci, dependencies
• Only suggest labels that genuinely match the issue content

Step 5: Present Recommendations

Show all recommendations for this issue and wait for approval:

Issue #42: "Improve page load time for dashboard"
Age: 4 months | Labels: none

Completion check: Possibly completed
  - Commit a1b2c3d "Optimize dashboard queries" (2 months ago) addresses this
  - Commit e4f5g6h "Add CDN for static assets" (3 months ago) also related

Task list: 2 of 4 items appear done
  - [x] Optimize database queries (commit a1b2c3d)
  - [x] Add CDN for static assets (commit e4f5g6h)
  - [ ] Lazy load below-fold components (no evidence found)
  - [ ] Add performance monitoring (no evidence found)

Suggested labels: performance, enhancement

Recommended actions:
  1. Update task list (check off 2 items)
  2. Add labels: performance, enhancement
  3. Add "triaged" label

Close as completed? No - 2 tasks remain open

Then ask what to do. Accept all, modify, or skip.

Step 6: Execute Approved Actions

Only execute what was approved. Use:

• gh issue close N --comment "..." for closing
• gh issue edit N --body "..." for updating task lists
• gh issue edit N --add-label "label1,label2" for labeling

Step 7: Mark as Triaged

After processing (whether changes were made or not), add the "triaged" label:

gh issue edit N --add-label "triaged"

Phase 3: Session Summary

After the batch is processed (or user stops early), show:

Triage Session Summary
━━━━━━━━━━━━━━━━━━━━━
Batch:                10 of 250 open issues
Closed as completed:   3
Task lists updated:    4
Labels added:         12
Skipped (no changes):  4
Remaining untriaged: 240

Run /triage-backlog again to process the next batch.

Common Mistakes

Mistake	Fix
Closing issues that are only partially done	If task list items remain, don't close - update the task list instead
Adding too many labels	Stick to 1-3 highly relevant labels per issue
Guessing at completion	Only mark completed when there's clear evidence (commits, code)
Editing without approval	Always present recommendations and wait
Forgetting to mark triaged	Always add "triaged" label after processing, even if no changes made
Creating labels without checking	Always use gh label create which is idempotent

Related Commands

• /fix-gh-issue - Fix a specific GitHub issue end-to-end
• /break-into-gh-issues - Split large work into manageable issues