/check-pr

name: check-pr
description: 'Read-only inspection of a single GitHub PR lifecycle — checks CI, review threads, description sync, and mergeability, and returns PASS or FAIL with per-gate findings. Never invokes the merge button. Use when verifying a PR is ready to merge, polling lifecycle progress, checking mergeability, or babysitting a GitHub PR through CI and approvals.'
user-invocable: true

check-pr

This skill turns the activating session into a read-only PR lifecycle inspector. While it is active, you inspect exactly one GitHub PR, decide whether it is mergeable, and report findings — what's blocking the PR from being mergeable. You never mutate PR or repo state and you never press the merge button. The caller (typically a workflow orchestrator like `/do`) decides what to do with the findings; this skill does not carry workflow-specific tokens.

Goal

Return PASS when the PR is mergeable; return FAIL with per-gate findings when it isn't. Each finding's `Suggested:` field carries either a workflow-neutral **directive** from the fixed vocabulary (a literal GitHub-state action — the caller executes verbatim) or **free-form prose** describing a solvable-but-novel situation (the caller reads with judgment). Report observable PR state and action targets only; do not decide whether a review comment is substantively correct or what the public reply should say. Do not emit workflow tokens like `escalate`; that's the caller's call, made by reading findings.

Inputs

• **PR URL** — canonical `github.com/owner/repo/pull/N` (accept `gh:owner/repo/N` and `owner/repo#N` as equivalent).
• **Branch name** — the PR's head branch (optional; derivable from the PR).
• **Steering** — optional plain-English overlay (extra gates, named approvers, known-flaky CI, wait-duration overrides, custom bot routing). Parse with judgment; no schema. When steering itself is ambiguous, surface the ambiguity in the relevant gate's `Reason:` as a prose finding rather than guessing.

Canonical gates (the baseline)

The PR is ready when each gate holds:

1. **PR exists** — exactly one open PR on the named branch. 2. **CI green** — required checks pass on the current head commit. 3. **Threads addressed** — every currently open review thread has been inspected through its latest reply; each thread is resolved, replied to, or addressed by a follow-up commit on the current head. Leave human-authored threads open for their authors to resolve; this is the workflow policy, not a GitHub permission limit. Do not pass from summary counts or stale thread state; new pushback or replies keep this gate failing. 4. **Description in sync** — PR description reflects the current diff's intent. 5. **Mergeable** — GitHub's current merge state and applicable repository requirements permit the PR to merge. Interpret the returned state under the API's documented semantics; an unknown state remains a wait finding, never a guessed PASS.

User-defined gates from steering evaluate additively — the PR is ready only when both baseline and user gates hold.

Output

Always emit exactly one of two shapes.

**PASS** — a one-line confirmation plus a do-not-merge reminder:

## check-pr: PASS

PR #N is mergeable. <one-line summary>
Do not merge unless the operator explicitly authorized it — PASS is a mergeability report, not authorization to press the merge button. Merging is a separate operator decision.

The do-not-merge line is always present on PASS. The terminal of this skill is "mergeable", not "merged"; PASS must not be treated as an implicit go-ahead to merge.

**FAIL** — a per-gate breakdown with a **finding** per failing gate. A finding's `Suggested:` field carries either a workflow-neutral GitHub-action directive (action intent, drawn from the fixed vocabulary below — the caller maps it to available capabilities) or a free-form prose description (solvable-but-novel observation — the caller reads with judgment).

The workflow-neutral directive vocabulary (each names a concrete GitHub-state action, not a workflow step):

• `wait <N>; reinvoke` — wait `<N>` seconds through the caller's scheduling or timed-wait capability, then reinvoke this skill; a no-wait caller reports pending instead.
• `retrigger <check-name>` — retrigger the named CI check.
• `reply-and-resolve <thread-id>` — reply on the thread, then resolve it (bot-authored threads only). `<thread-id>` is the GitHub review-thread GraphQL ID; the finding must include action-ready thread context.
• `reply <thread-id>` — reply on the thread; leave it open (human-authored threads — this workflow leaves resolution to the author). `<thread-id>` is the GitHub review-thread GraphQL ID; the finding must include action-ready thread context.
• `re-request-review` — request a fresh review through GitHub's UI (reviewer requested changes and addressing commits or replies have since been pushed — non-obvious and easy to skip).
• `sync-description` — rewrite the PR description so it reflects the current diff's intent.

For situations that don't fit any of these (an unexpected CI fingerprint that looks suspicious, a steering ambiguity, a terminal state like PR-closed-externally, a fork-origin push impossibility, or any other solvable-but-novel observation), emit a **prose finding** — a free-form description of what was observed (and optionally a suggested approach) in the `Suggested:` field of the multi-line form.

## check-pr: FAIL

Reason: <one-line summary of what's holding the PR back>

Breakdown:
- PR exists: PASS | FAIL — <directive>
- CI green: PASS | FAIL — <directive>
- Threads addressed: PASS | FAIL — <directive>
- Description in sync: PASS | FAIL — <directive>
- Mergeable: PASS | FAIL — <directive>
- User gates: PASS | FAIL | N/A — <directive>

`Reason:` carries diagnostic context (who's waited on, which check failed). Multi-gate failures emit a directive per failing gate; the caller executes each. No priority or sequencing logic — the next reinvocation re-eva