github-triage

# GitHub Triage Triage a repository's open GitHub issues and pull requests. Optionally clear ready PRs first (merge passing bot PRs and maintainer-approved PRs, review never-reviewed ones), then close issues that are already resolved (with a comment citing the PR or commit that resolved them), make sure issues and the pending PRs that fix them reference each other, and assign a **local-only** priority and change-size estimate to every issue that is still outstanding. ## When to Use - When the user runs `/github-triage` to groom or review a repository's open issues and pull requests. - When an issue backlog has drifted: resolved work left open, fixes landed without closing their issues, or PRs in flight that never linked their issue. - When ready PRs have piled up (passing dependency bumps, approved-and-green PRs) or PRs are sitting unreviewed. ## When NOT to Use - Do not invoke automatically. This skill performs irreversible GitHub writes (merging PRs, closing issues, posting comments) and runs only on explicit invocation. - Do not use to apply priority/effort *labels* on GitHub. Priority and size are presented locally only and are never posted (see Safety Rules). - Do not use as a substitute for a human's final merge decision — every merge is proposed for explicit approval, never performed autonomously. ## Core Principles 1. **Writes are gated.** Compute the full triage first, present every proposed write — merges included — for review, and execute nothing until the user approves. 2. **Evidence before closing.** Never close an issue without a concrete, cited reason (a merged PR or a commit on the default branch). When evidence is weak or ambiguous, leave the issue outstanding and flag it for review. 3. **Priority and size stay local.** They are an internal planning aid for the user, never written to GitHub. ## Workflow ### Phase 0: Select the target repository ```bash gh auth status # confirm gh is authenticated git rev-parse --is-inside-work-tree # is PWD a git repository? git remote -v # enumerate remotes ``` Determine the set of **distinct GitHub-hosted repositories** among the remotes. A remote is GitHub-hosted when its URL host is `github.com`, in any of these forms: - `https://github.com/OWNER/REPO(.git)` - `git@github.com:OWNER/REPO(.git)` - `ssh://git@github.com/OWNER/REPO(.git)` Normalize each to `OWNER/REPO` and de-duplicate (a fork setup may have `origin` and `upstream` pointing at different GitHub repos; multiple remotes pointing at the *same* `OWNER/REPO` count once). Selection rule: | Situation | Action | |-----------|--------| | Exactly one distinct GitHub repo | Use it as the default — do not prompt. | | Not a git repo, or zero GitHub remotes | Ask the user for the `OWNER/REPO` to triage. | | More than one distinct GitHub repo | Use **AskUserQuestion** to let the user pick which `OWNER/REPO`. | > GitHub Enterprise hosts cannot be auto-detected reliably. If the user works on a > GHE instance, ask for `OWNER/REPO` and have them set `GH_HOST` / use `gh`'s > configured host. Confirm the resolved repo back to the user before continuing. Store the result as `REPO="OWNER/REPO"` and pass `-R "$REPO"` to every `gh` call. Validate it against `^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$` before use, so a malformed or hostile remote URL never flows into a command. ### Phase 1: Gather issues and context ```bash # Open issues (gh issue list excludes PRs by default) gh issue list -R "$REPO" --state open --limit 1000 \ --json number,title,body,labels,assignees,comments,reactionGroups,createdAt,updatedAt,url # Open PRs — candidates for "pending fix" (issue phase) and PR triage (Phase 2) 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 # Recently merged PRs — candidates for "already resolved" gh pr list -R "$REPO" --state merged --limit 300 \ --json number,title,body,mergedAt,url,closingIssuesReferences ``` `closingIssuesReferences` lists the issues a PR is linked to close — populated by any of GitHub's closing keywords (`close`/`closes`/`closed`, `fix`/`fixes`/`fixed`, `resolve`/`resolves`/`resolved`) in the PR body, or by a manual UI link. It is the strongest available signal. For issues it does not cover, also search commit messages on the default branch. Resolve the default branch authoritatively from the selected repo (not from local `origin/HEAD`, which may be unset or point at the wrong remote): ```bash default_branch=$(gh repo view "$REPO" --json defaultBranchRef --jq .defaultBranchRef.name) # Anchor the issue number so #12 does not match #120, #123, … git log --oneline "origin/$default_branch" \ | grep -iE "(close|fix|resolve)[sd]? +#<N>([^0-9]|$)" ``` ### Phase 2: Triage open pull requests (optional) Handle PRs **before** issues: merging ready PRs here means the "already resolved" check in the issue phase sees the work those merges just landed. If there are no open PRs, skip this phase. Otherwise summarize the open PRs and **ask the user whether to handle PRs now** (AskUserQuestion: handle PRs / skip to issues). If they skip, go straight to issue classification. Classify each open PR from its review, CI, and merge state. The field shapes below are what `gh pr ... --json` actually returns — rely on them, not on intuition: - **Ready to merge** = `mergeable == "MERGEABLE"` **and** `mergeStateStatus == "CLEAN"` **and** CI is not blocking (below). `CLEAN` is GitHub's server-side "no conflicts, not behind, not draft, required checks green" verdict — any other `mergeStateStatus` (`BEHIND`, `UNSTABLE`, `BLOCKED`, `DIRTY`, `DRAFT`, …) is **not ready**. Treat `mergeable == "UNKNOWN"` (GitHub recomputes mergeability lazily, especially right after another merge) as **not ready** — re-poll briefly or skip; never merge on it. - **CI not blocking** — scan `statusCheckRollup` (keyed on `__typename`) and reject the PR only on a real problem: a **hard failure** (a `CheckRun` whose `conclusion` is `FAILURE`/`CANCELLED`/`TIMED_OUT`/`ACTION_REQUIRED`/`STARTUP_FAILURE`/`STALE`, or a `StatusContext` whose `state` is `FAILURE`/`ERROR`), or anything **still running** (a `CheckRun` `status` of `QUEUED`/`IN_PROGRESS`/`WAITING`/`PENDING`, or a `StatusContext` `state` of `PENDING`/`EXPECTED` — wait, do not merge yet). `SUCCESS`, `NEUTRAL`, and `SKIPPED` are **fine** and must not block (e.g. a CodeQL run that reports `NEUTRAL` on a dependency bump — a green Dependabot PR is `CLEAN` with a `NEUTRAL` CodeQL check). An **empty** rollup is *no CI* — a distinct state, never treated as ready. `mergeStateStatus == "CLEAN"` already reflects *required*-check status; use the rollup to catch failing/pending *non-required* checks. - **Bot/automated** = `author.is_bot == true`. Match the auto-merge **allowlist** against `author.login` after normalizing away `gh`'s rendering — strip a leading `app/` and a trailing `[bot]` (gh returns Dependabot as `app/dependabot` in some versions and `dependabot[bot]` in others; normalize both to `dependabot`). Allowlisted by default: `dependabot`, `renovate`, plus any the user names. A passing PR from a non-allowlisted bot is reported, never offered for merge. - **Maintainer-approved** = `latestReviews` has an entry with `state == "APPROVED"` whose `authorAssociation` is `OWNER`/`MEMBER`/`COLLABORATOR` and whose `author.login` is not the PR author. Do **not** use `reviewDecision == "APPROVED"` alone: it is branch-protection-driven and is `null` on repos with no required-review rule, so it both over-trusts (cannot confirm write access) and misses genuine approvals. - **Never reviewed** = `latestReviews` has no `APPROVED`/`CHANGES_REQUESTED` entry from anyone other than the PR author (a fork "review disabled" bot comment is not review). | Category | Condition | Offered action | |----------|-----------|----------------| | Mergeable bot PR | allowlisted bot + ready + not draft | Offer **incremental, in-order merge** | | Approved & ready | maintainer-approved + ready + not draft | Prompt to merge | | Never reviewed | **non-bot** + only the author has reviewed (or no reviews) + not draft | Offer to **spawn a review subagent** | | Needs work | draft, hard CI failure, pending CI, conflicts, behind, changes requested, or a bot PR that is not ready | Report only — no action offered | ("ready" already subsumes CI-not-blocking. Review subagents are for human-authored PRs — a bot's dependency bump that is not ready is reported as Needs work, not reviewed.) Present the categorized PRs and offer the applicable actions via AskUserQuestion. **Incremental, in-order merge** (bot PRs and approved-ready PRs): confirm the merge set and the merge method first (merging is irreversible), then merge **one at a time, oldest first**. Choose a method the repo allows and fail closed if it does not: ```bash gh repo view "$REPO" --json mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed # positional repo, not -R ``` For each PR in order, **re-verify immediately before merging** (state drifts after each merge — a landed PR can leave the next `BEHIND`, conflicting, or recomputing), merge **synchronously**, then **confirm it landed** before advancing: ```bash gh pr view <N> -R "$REPO" --json isDraft,reviewDecision,mergeable,mergeStateStatus,statusCheckRollup # proceed only if still ready: not draft, mergeable == MERGEABLE, mergeStateStatus == CLEAN, CI not blocking gh pr merge <N> -R "$REPO" --<method> # never --auto, never --admin gh pr view <N> -R "$REPO" --json state # expect "MERGED" before moving to the next PR ``` Stop and report if a PR is no longer ready (including `mergeable == "UNKNOWN"`), if the merge did not land, or if any required check is not green — never force, `--admin`, `--auto`, or skip a check. For bot PRs, surface the dependency and version jump (e.g. major bumps) in the gate so the user can decide with context. **Review subagents** (never-reviewed PRs): when the user opts in, spawn one **Agent** per PR — all in a single assistant message so they run in parallel. Each subagent reviews one PR's diff and returns a structured review; write each to `github-pr-<number>-review.md` in the working directory (overwriting any prior file for that PR). Reviews are **read-only and never posted to GitHub**. See [references/reviewing-prs.md](references/reviewing-prs.md) for the subagent prompt, review rubric, and file format. After any merges, **re-fetch** the merged-PR list (the Phase 1 `--state merged` query) so the issue phase can detect issues those merges resolved. ### Phase 3: Classify each open issue Sort every open issue into exactly one bucket. **Bucket A — Already resolved (the work landed, the issue was left open).** Requires concrete evidence; prefer corroboration over a single weak signal: - A **merged** PR lists the issue in `closingIssuesReferences`, or its title/body references `#N` alongside a closing keyword. (Strongest.) - A commit on the default branch references `#N` with a closing keyword. - The behavior the issue asks for **demonstrably exists in the current code** — verify by reading the relevant code with Grep/Read, do not assume. A different or partial implementation does *not* resolve the issue. → Proposed write: close the issue with a comment that names the resolving PR/commit. ```bash 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 issue describes. The goal is that the issue and PR **reference each other** — fill only genuine gaps, and prefer non-destructive writes: - No reference in either direction → post a pointer comment (non-destructive) on the side that lacks it. A mention of `#<PR>` / `#<N>` creates a cross-reference that GitHub mirrors into the other's timeline. ```bash gh issue comment <N> -R "$REPO" -b "A fix is in progress in #<PR>." ``` - Already linked in at least one direction → record "already linked — no action". Do **not** edit the PR body unless the user explicitly wants the PR to *auto-close* the issue on merge. A comment establishes a reference but does **not** trigger auto-close — only a closing keyword in the PR **body** or a **commit message** does. When the user opts in, never clobber the description: re-fetch the body immediately before editing and pass it via stdin, so untrusted PR text never transits a shell-interpolated string: ```bash body=$(gh pr view <PR> -R "$REPO" --json body --jq .body) printf '%s\n\nCloses #%s\n' "$body" "<N>" | gh pr edit <PR> -R "$REPO" --body-file - ``` Do not duplicate links that already exist. **Bucket C — Outstanding (no resolution, no pending PR).** Assign, **locally only**, a priority and a change-size estimate (next section). ### Phase 4: Score outstanding issues (LOCAL ONLY) **Priority** — `Critical` / `High` / `Medium` / `Low`. Weigh: - *Impact / severity* — security, data loss, crash, or correctness bugs rank above enhancements; docs/cosmetic rank lowest. Existing labels (`security`, `bug`, `crash`, `regression`) are strong signals. - *Reach* — how many users/workflows are affected. - *Signal* — reactions (👍), duplicate reports, age with continued activity. - *Urgency* — blocks a release, has a deadline, or has an active regression. **Change size** — the effort proxy, expressed as a `size/*` T-shirt bucket from the **estimated** total changed lines (additions + deletions, ignoring generated/vendored files), using the Kubernetes/Prow thresholds: | Bucket | Estimated changed lines | |--------|-------------------------| | `size/XS` | 0–9 | | `size/S` | 10–29 | | `size/M` | 30–99 | | `size/L` | 100–499 | | `size/XL` | 500–999 | | `size/XXL` | 1000+ | Estimate by reasoning about the codebase: which files/areas the change touches and whether it is localized or cross-cutting. When feasible, **open the implicated files** (Grep/Read) before estimating rather than guessing from the title — the line and file counts should reflect what the change actually touches. Because the issue is not yet implemented, the diff is a *prediction* — so: - Show the estimated **lines** and **files touched**, plus a one-line **basis of estimate**, so the reasoning is auditable. - When an issue is too vague or needs design/investigation before it can be sized, mark it `unsized — needs investigation` instead of guessing. - Size measures *volume*, not *difficulty*. When a small change is genuinely hard (subtle crypto, concurrency, broad blast radius), add a short complexity caveat so an XS/S issue is not mistaken for trivial. Never post priority, size, or the basis of estimate to GitHub. ### GATE 1: Present the full triage for review Present everything in one view. Make the local-only section unmistakably local. ```markdown ## Triage for OWNER/REPO (N open issues) ### Proposed closes (already resolved) — WRITES to GitHub | Issue | Title | Evidence | Draft comment | |-------|-------|----------|---------------| | #123 | ... | merged PR #130 | "Resolved by #130 …" | ### Proposed cross-links (pending PR) — WRITES to GitHub