claude-engineering-plugin/.claude/commands/triage-prs.md

name, description, argument-hint, disable-model-invocation, allowed-tools

name	description	argument-hint	disable-model-invocation	allowed-tools
triage-prs	Triage all open PRs with parallel agents, label, group, and review one-by-one	[optional: repo owner/name or GitHub PRs URL]	true	Bash(gh *), Bash(git log *)

Triage Open Pull Requests

Review, label, and act on all open PRs for a repository using parallel review agents. Produces a grouped triage report, applies labels, cross-references with issues, and walks through each PR for merge/comment decisions.

Step 0: Detect Repository

Detect repo context:

• Current repo: !gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "no repo detected"
• Current branch: !git branch --show-current 2>/dev/null

If $ARGUMENTS contains a GitHub URL or owner/repo, use that instead. Confirm the repo with the user if ambiguous.

Step 1: Gather Context (Parallel)

Run these in parallel:

1. List all open PRs:

   gh pr list --repo OWNER/REPO --state open --limit 50
   

2. List all open issues:

   gh issue list --repo OWNER/REPO --state open --limit 50
   

3. List existing labels:

   gh label list --repo OWNER/REPO --limit 50
   

4. Check recent merges (to detect duplicate/superseded PRs):

   git log --oneline -20 main
   

Step 2: Batch PRs by Theme

Group PRs into review batches of 4-6 based on apparent type:

• Bug fixes - titles with fix, bug, error descriptions
• Features - titles with feat, add, new functionality
• Documentation - titles with docs, readme, terminology
• Configuration/Setup - titles with config, setup, install
• Stale/Old - PRs older than 30 days

Step 3: Parallel Review (Team of Agents)

Spawn one review agent per batch using the Task tool. Each agent should:

For each PR in their batch:

1. Run gh pr view --repo OWNER/REPO <number> --json title,body,files,additions,deletions,author,createdAt
2. Run gh pr diff --repo OWNER/REPO <number> (pipe to head -200 for large diffs)
3. Determine:
   • Description: 1-2 sentence summary of the change
   • Label: Which existing repo label fits best
   • Action: merge / request changes / close / needs discussion
   • Related PRs: Any PRs in this or other batches that touch the same files or feature
   • Quality notes: Code quality, test coverage, staleness concerns

Instruct each agent to:

• Flag PRs that touch the same files (potential merge conflicts)
• Flag PRs that duplicate recently merged work
• Flag PRs that are part of a group solving the same problem differently
• Report findings as a markdown table
• Send findings back via message when done

Step 4: Cross-Reference Issues

After all agents report, match issues to PRs:

• Check if any PR title/body mentions Fixes #X or Closes #X
• Check if any issue title matches a PR's topic
• Look for duplicate issues (same bug reported twice)

Build a mapping table:

| Issue | PR | Relationship |
|-------|-----|--------------|
| #158  | #159 | PR fixes issue |

Step 5: Identify Themes

Group all issues into themes (3-6 themes):

• Count issues per theme
• Note which themes have PRs addressing them and which don't
• Flag themes with competing/overlapping PRs

Step 6: Compile Triage Report

Present a single report with:

1. Summary stats: X open PRs, Y open issues, Z themes
2. PR groups with recommended actions:
   • Group name and related PRs
   • Per-PR: #, title, author, description, label, action
3. Issue-to-PR mapping
4. Themes across issues
5. Suggested cleanup: spam issues, duplicates, stale items

Step 7: Apply Labels

After presenting the report, ask user:

"Apply these labels to all PRs on GitHub?"

If yes, run gh pr edit --repo OWNER/REPO <number> --add-label "<label>" for each PR.

Step 8: One-by-One Review

Use AskUserQuestion to ask:

"Ready to walk through PRs one-by-one for merge/comment decisions?"

Then for each PR, ordered by priority (bug fixes first, then docs, then features, then stale):

Show the PR:

### PR #<number> - <title>
Author: <author> | Files: <count> | +<additions>/-<deletions> | <age>
Label: <label>

<1-2 sentence description>

Fixes: <linked issues if any>
Related: <related PRs if any>

Show the diff (trimmed to key changes if large).

Ask for decision:

Use AskUserQuestion:

• Merge - Merge this PR now
• Comment & skip - Leave a comment explaining why not merging, keep open
• Close - Close with a comment
• Skip - Move to next without action

Execute decision:

• Merge: gh pr merge --repo OWNER/REPO <number> --squash
  • If PR fixes an issue, close the issue too
• Comment & skip: gh pr comment --repo OWNER/REPO <number> --body "<comment>"
  • Ask user what to say, or generate a grateful + specific comment
• Close: gh pr close --repo OWNER/REPO <number> --comment "<reason>"
• Skip: Move on

Step 9: Post-Merge Cleanup

After all PRs are reviewed:

1. Close resolved issues that were fixed by merged PRs
2. Close spam/off-topic issues (confirm with user first)
3. Summary of actions taken:

   ## Triage Complete
   
   Merged: X PRs
   Commented: Y PRs
   Closed: Z PRs
   Skipped: W PRs
   
   Issues closed: A
   Labels applied: B
   

Step 10: Post-Triage Options

Use AskUserQuestion:

1. Run /release-docs - Update documentation site if components changed
2. Run /changelog - Generate changelog for merged PRs
3. Commit any local changes - If version bumps needed
4. Done - Wrap up

Important Notes

• DO NOT merge without user approval for each PR
• DO NOT force push or destructive actions
• Comments on declined PRs should be grateful and constructive
• When PRs conflict with each other, note this and suggest merge order
• When multiple PRs solve the same problem differently, flag for user to pick one
• Use Haiku model for review agents to save cost (they're doing read-only analysis)