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 mer