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) or issue-first development workflow and PR creation (use git-workflow).
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="plan/${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

See references/templates.md for issue close/create templates and references/example-session.md for a complete grooming session walkthrough.

Example 1: Closing a Resolved Issue

gh issue close 123 --comment "Resolved in PR #456

Added input validation for single-object payloads.

Changes:
- Added type check in process_input()
- Added test for single-object case

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

Example 2: Creating a Follow-Up Issue

gh issue create --title "perf: Optimize database queries in user search" \
  --body "During PR #458, identified N+1 query in user search. Need to add eager loading." \
  --label "enhancement,performance"

Troubleshooting

Error: Too many PRs to review

• Focus on most recent PRs first
• Split into multiple sessions, document stopping point
• Default to last 15 PRs unless specified otherwise

Error: Can't find issues referenced in PR

• Check PR body AND individual commit messages
• Look for variations: "close", "fix", "resolve" (with/without #)
• If genuinely missing, create retrospective issue

Error: Found many duplicate issues

• Consolidate into a canonical issue
• Close duplicates with link to canonical
• Consider improving issue labels/search to prevent future duplicates