backlog-grooming

name	backlog-grooming
description	Systematic GitHub backlog maintenance: review merged PRs, close resolved issues, identify gaps, and create missing issues. Use when asked to groom the backlog, clean up the issue tracker, or review recent work. Do NOT use for PR code review (use comprehensive-pr-review).
metadata	{"author":"Geoff","version":"1.0.0"}

Backlog Grooming

Systematically review recent work, close resolved issues, identify gaps, and maintain a clean issue backlog.

Instructions

Step 1: Initialize Progress Tracking

Create a dated progress file:

DATE=$(date +%Y-%m-%d)
PROGRESS_FILE="prompts/claude-comm/${DATE}_BACKLOG_GROOMING.md"

Step 2: Fetch and Analyze Recent PRs

gh pr list --state merged --limit 15 --json number,title,mergedAt,body,url

For each PR, extract:

• Issues referenced (closes #N, fixes #N, resolves #N)
• Work done (features, fixes, refactors)
• Gaps (work done without corresponding issues)

Step 3: Verify Issue Resolution

For each issue referenced in PRs:

gh issue view 123 --json state,title,labels

Decision matrix:

• Fully resolved -> Close with comment referencing PR
• Partially resolved -> Update with progress comment
• Not resolved -> Keep open, remove incorrect PR reference
• Spawned new work -> Create follow-up issue, close original

Step 4: Close Resolved Issues

gh issue close 123 --comment "Resolved in PR #456. [Description of fix]. Changes: [list]. Closes via: [PR URL]"

Step 5: Check for Duplicates Before Creating New Issues

gh issue list --search "keyword" --state all
gh issue list --label "bug" --state open

Step 6: Create Missing Issues

For gaps identified (features, bugs fixed, follow-up work) that have no existing issue:

gh issue create --title "Issue title" --body "Description" --label "label1,label2"

Step 7: Finalize Progress File

Complete the summary with statistics: PRs analyzed, issues closed, issues created, issues updated, backlog health before/after.

Examples

Example 1: Closing a Resolved Issue

gh issue close 293 --comment "Resolved in PR #306

Decomposed ContentView monolith into focused sub-views.

Changes:
- Extracted MysticalJournalIcon, ConceptExplainerView, FlowReviewSheet
- Extracted all views from ContentView
- Deduplicated primaryID

Thank you for reporting! Fix is merged and available."

Example 2: Creating a Follow-Up Issue

gh issue create --title "feat: Add automatic retry for failed journal sync" \
  --body "During PR #XXX, identified that failed sync entries are not retried. Need retry with exponential backoff." \
  --label "enhancement,frontend"

Troubleshooting

Error: Too many PRs to review

• Focus on most recent PRs first
• Split into multiple sessions, document stopping point

Error: Found many duplicate issues

• Consolidate into a canonical issue
• Close duplicates with link to canonical