/github-backlog-triage

name: github-backlog-triage
description: 'Use when the user invokes backlog triage for a GitHub repo''s open issues and PRs. Not for proactive triage, non-GitHub trackers, or single bug issues: use github-bug-report-triage.'
disable-model-invocation: true

GitHub backlog triage

Contract

| Field | Bound contract | |---|---| | Trigger | The user explicitly invokes backlog triage for a GitHub repository's open pull requests and issues. | | Authority | Remote: merges selected pull requests, closes evidenced resolved issues, and posts missing cross-links on GitHub; requires explicit human invocation. No write runs until the user approves the final set. Never triage proactively. | | Side effect | After a complete approval gate, optionally merge selected ready pull requests, close evidenced resolved issues, post missing cross-links, and write local review or triage reports. Priority and size estimates are local-only and never posted to GitHub. | | Done | All open items are classified; only the user-approved GitHub writes execute with per-action safety checks; unresolved items retain local-only priority and size estimates; and any requested local reports are saved. |

Inputs

• A working directory that is a git repository with one or more GitHub-hosted remotes, OR a user-supplied `OWNER/REPO`. Optional: a user-named bot auto-merge allowlist beyond the default `dependabot` and `renovate`; a display cutoff for the outstanding table (default 32); a user request to edit a PR body so a pending fix auto-closes its issue on merge.
• `gh` must be authenticated (`gh auth status`). The resolved `OWNER/REPO` is validated against `^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$` before any `gh -R "$REPO"` call.

Procedure

1. **Select the target repository.** Run `gh auth status`, `git rev-parse --is-inside-work-tree`, `git remote -v`. A remote is GitHub-hosted when its URL host is `github.com` (`https://github.com/OWNER/REPO(.git)`, `git@github.com:OWNER/REPO(.git)`, or `ssh://git@github.com/OWNER/REPO(.git)`). Normalize each to `OWNER/REPO` and de-duplicate. Exactly one distinct GitHub repo: use it without prompting. Zero (not a git repo, or no GitHub remote): ask the user for `OWNER/REPO`. More than one: ask the user to pick. For GitHub Enterprise, ask for `OWNER/REPO` and rely on the user's `GH_HOST`/`gh` host config; confirm the resolved repo back before continuing. Store `REPO="OWNER/REPO"` and pass `-R "$REPO"` to every `gh` call. Done when: REPO is set to a validated OWNER/REPO matching the required pattern, gh auth status exits 0, and every subsequent gh call passes -R "$REPO".

2. **Gather issues and context.** Fetch open issues, open PRs, and recently merged PRs: Done when: open issues, open PRs, and recently merged PRs are fetched as JSON, the default branch is resolved from the repo, and resolution signals are gathered from closingIssuesReferences and default-branch commits.

   gh issue list -R "$REPO" --state open --limit 1000 --json number,title,body,labels,assignees,comments,reactionGroups,createdAt,updatedAt,url
   gh pr list -R "$REPO" --state open --limit 1000 --json number,title,body,author,isDraft,reviewDecision,latestReviews,mergeable,mergeStateStatus,statusCheckRollup,labels,createdAt,headRefName,url,closingIssuesReferences
   gh pr list -R "$REPO" --state merged --limit 300 --json number,title,body,mergedAt,url,closingIssuesReferences

`closingIssuesReferences` is the strongest resolution signal (populated by GitHub closing keywords or a manual UI link). For issues it does not cover, search default-branch commits. Resolve the default branch authoritatively from the repo, not from local `origin/HEAD`:

   default_branch=$(gh repo view "$REPO" --json defaultBranchRef --jq .defaultBranchRef.name)
   git log --oneline "origin/$default_branch" | grep -iE "(close|fix|resolve)[sd]? +#<N>([^0-9]|$)"

3. **Triage open pull requests when any are open.** Summarize them and ask whether to handle PRs now or skip to issues, then follow `references/pr-triage.md`, which covers classification, incremental merges, review subagents, and per-item approved actions (staleness comments, closes, reviewer requests, status comments, labeling) executed only on per-item user approval. After merges, re-fetch the step-2 merged-PR list before classifying issues. Done when: every open PR is classified, approved merges landed one at a time with re-verification, opted-in reviews remain read-only, and every per-item write action ran only after its own approval.

4. **Classify each open issue** into exactly one bucket. Done when: every open issue is placed into exactly one bucket (Already resolved, Pending PR, or Outstanding), and each bucket assignment carries its evidence or stated lack thereof.

• Bucket A: Already resolved (the work landed, the issue was left open). Requires concrete evidence, preferring corroboration: a merged PR lists the issue in `closingIssuesReferences` or references `#N` with a closing keyword (strongest); a default-branch commit references `#N` with a closing keyword; or the behavior the issue asks for demonstrably exists in the current code, verify by reading the relevant code, do not assume; a different or partial implementation does not resolve it. Proposed write: close with a comment naming the resolving PR/commit:

     gh issue close <N> -R "$REPO" -c "Resolved by #<PR> (<short reason>). Closing as the change is now on $default_branch."

• Bucket B: Pending PR would resolve it (an open PR addresses the issue). Detect by either direction: the open PR's `closingIssuesReferences` includes the issue; the issue body/comments link the PR; or an open PR clearly fixes the same thing. The goal is that issue and PR reference each other; fill only genuine gaps, prefer non-destructive writes. No reference in either direction: post a pointer comment on the side that lacks it (`gh issue comment <N> -R "$REPO" -b "A fix is in progre