spboyer/repo-issue-triage/repo-issue-triage

Repo Issue Triage

Automates the process of auditing all open GitHub issues against pending PRs, recently merged PRs, and the current main branch codebase, then produces a structured report with close/keep recommendations and actionable work items.

Quick Reference

When to Use This Skill

• Periodic issue hygiene (weekly/monthly triage)
• Sprint planning — identify what's already covered by PRs
• Pre-release audit — find issues that can be closed
• Post-merge cleanup — close issues covered by recent merges
• PR health monitoring — CI status, review threads, approvals

Workflow

Execute these 7 phases in order. Use parallel tool calls wherever noted.

Phase 1: PR HEALTH CHECK

Check the status of the user's open PRs first. This is always the starting point — address any failing CI or unresolved review threads before moving to issue triage.

Parallel calls:

For each PR owned by the user:
  - CI status: gh pr checks {number} → count failures/passes/running
  - Review threads: GraphQL reviewThreads → count unresolved
  - Approvals: reviews → list approved-by

Output table:

| PR | Title | CI | Approvals | Unresolved Threads | Status |

Actions if issues found:

• CI failures → fetch job logs, identify and fix
• Unresolved threads → read comments, address or resolve
• No approvals → note as "awaiting review"

Phase 2: FETCH ALL DATA

Fetch all open issues, open PRs, and recently merged PRs in parallel.

Parallel calls:

gh issue list --state open --limit 500
gh pr list --state open --limit 100
gh pr list --state merged --limit 30  (recent merges)

Extract into structured format: number | title | labels | assignees

Important: Use --limit 500 for issues. Paginate if repo has more.

Use CLI (gh) for bulk fetching — it's faster than individual API calls.

Phase 3: BUILD COVERAGE MAP

Build a mapping of what PRs (open and merged) cover which issues.

Method 1: Direct links

• Scan PR titles/bodies for "Fixes #N", "Closes #N", "fix #N"
• Check issue bodies for PR references

Method 2: Keyword matching

• Match PR titles against issue titles using topic keywords
• Use regex patterns for common coverage relationships

Method 3: Known mappings

• If the user has been working in this session, use SQL tables

from prior work to pre-populate known coverage

Store in SQL:

CREATE TABLE issue_triage (
  number INTEGER PRIMARY KEY,
  title TEXT,
  labels TEXT,
  assignees TEXT,
  status TEXT DEFAULT 'pending',
  covered_by TEXT,
  reason TEXT,
  tier TEXT
);

Phase 4: DEEP ANALYSIS (Parallel Batches)

For issues not clearly mapped, do deep analysis using sub-agents.

Split issues into batches of ~100-120 and send to parallel explore agents. Each agent gets:

1. The batch of issues (number | title | labels | assignees)
2. The list of open PRs with descriptions of what they change
3. The list of recently merged PRs
4. Instructions to check the codebase for implemented features

Agent prompt pattern:

Read {batch_file} containing ~{N} GitHub issues for {owner}/{repo}.
 
For each issue, determine if it could be CLOSED or PARTIALLY addressed
by any of these recent changes:
 
MERGED PRs:
- #{num}: {title} ({summary of changes})
 
OPEN PRs:
- #{num}: {title} ({summary of changes})
 
Also check the codebase in {repo_path} for any issues that might
already be implemented on main.
 
Output ONLY issues that are CLOSEABLE or PARTIALLY covered.
Format: #NUMBER | TITLE | STATUS (CLOSE/PARTIAL) | COVERED_BY | REASON

Key: Use explore agent type with a capable model (e.g., Codex)

for accurate codebase analysis. Run 4 batches in parallel.

Phase 5: VERIFY ON MAIN

For issues flagged as potentially fixed, verify against the codebase:

# Search for the fix
grep -r "keyword" --include="*.go" cli/
glob "**/*relevant_file*"
 
# Check recent commits
git log --oneline --grep="issue-keyword" -20
 
# Verify file exists
ls path/to/expected/implementation

Critical: Don't trust keyword matches alone. Verify the actual implementation exists and addresses the issue's requirements.

Phase 6: CATEGORIZE AND TIER

Assign each issue to a category using the classification rules.

Additionally, tier actionable issues:

Phase 7: REPORT

Generate the final report using the report template.

Report sections:

1. PR Health Status table
2. Closeable issues (with reasons)
3. Auto-close on merge issues
4. Partially covered issues (what's done, what remains)
5. Quick wins and actionable items
6. Category breakdown of remaining issues
7. Summary statistics

Output as a markdown file and open in the user's editor.

Closing Issues

When closing issues, always include a detailed comment explaining:

1. What PR or commit covers the issue
2. Specifically how the issue is addressed (mention code/features)
3. Any remaining gaps (for partial closures, note what's left)

Pattern:

Addressed by PR #{num} which {specific description of what the PR does}.
{Additional detail about how this resolves the issue's requirements}.

Do NOT use generic close messages like "Fixed" or "Resolved".

Batch Processing Guidelines

To avoid flooding the GitHub API:

MCP Tools Used

Error Handling

Reference Documentation

• Classification Rules — Decision tree for categorizing issues
• Report Template — Output format specification