doodledood/manifest-dev/check-pr

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. Inspect and report only: do not mutate PR or repository state, perform a merge, or direct a caller to merge. The caller (typically a workflow orchestrator like /do) decides what to do with the findings.

Goal

Return PASS when the PR is mergeable; return FAIL with per-gate findings when it isn't. Report observable PR state and action targets only.

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. Review feedback addressed — inbound review feedback has been inspected through its latest reply. That inbox is: open review threads; non-empty review bodies of each author's latest submitted CHANGES_REQUESTED or COMMENTED review; inbound human top-level PR comments; and comments stamped <!-- manifest-dev:review-pr --> (the marker is an inbox signal, not a skip). Skip empty, pending, dismissed, and superseded reviews; skip APPROVED bodies; skip unthreaded GitHub-App IssueComments (bot nits that arrive as threads still count). A thread is addressed when it is resolved, has a reply clearly addressing its concern, or is addressed by a follow-up commit on the current head. A review body or top-level comment is addressed when the PR author has later replied on the Conversation with a response clearly tied to that item, the review is dismissed, or a newer submitted review from the same reviewer supersedes it — a follow-up commit or unrelated later update does not address a body or comment. Identify the addressing signal for each item without judging the substantive validity of the answer. Leave human-authored threads open for their authors to resolve. Do not pass from summary counts or stale 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.

Include the reminder line on every PASS.

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.

reply and reply-and-resolve name a review-thread GraphQL ID. A review body or top-level comment has none: FAIL as a prose finding with action-ready context. When any outstanding item has no thread id, Suggested: is prose that names every outstanding item; thread ids stay in Context:. Do not invent a thread id. re-request-review answers review state, not unanswered content.

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, an unanswered review body or top-level comment, 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>
- Review feedback 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-evaluates state.

Example wait-in-progress FAIL (reviewer-pending — execute the sleep and reinvoke; waiting is the resolution, not a stuck signal):

## check-pr: FAIL
 
Reason: Reviewer @bob (per CODEOWNERS) has not approved; CI green, review feedback clean. Waiting is the resolution — execute the sleep and reinvoke.
 
Breakdown:
- Mergeable: FAIL — wait 600; reinvoke

Example terminal-condition FAIL (surfaced as a prose finding — no workflow token):

## check-pr: FAIL
 
Breakdown:
- PR exists: FAIL
  Reason: PR was closed externally by @bob at 2026-05-17T14:32Z.
  Suggested: Unrecoverable from automated inspection — caller should hand off to a human; reopening from the agent's path is forbidden.
  Context: GraphQL state `CLOSED`, last commit on head matches the diff at close time.

Multi-line per-gate form. When a failing gate has meaningful context the caller needs inline (especially reply <thread-id> / reply-and-resolve <thread-id> — the caller shouldn't have to re-fetch the thread to identify the target or understand why it blocks mergeability — or a review body / top-level comment with no thread id, or any prose-finding case where the observation is more than a single vocabulary token), the per-gate breakdown line expands into a named-field block:

- <gate>: FAIL
  Reason: <what was observed for this gate>
  Suggested: <either a vocabulary-token directive (action intent) OR free-form prose describing a suggested approach>
  Context: <supporting info: action targets, thread excerpt, check log, reviewer activity, IDs, GraphQL state, etc.>

Reason: and Context: are diagnostic. Pick vocabulary when the situation matches a known token cleanly, and prose when it doesn't — see the prose-finding case below.

Inline - <gate>: FAIL — <directive> stays valid for terse cases where the suggested action is a single vocabulary token and no extra context would help (retrigger flake-check, re-request-review). Pick the shape per gate based on whether there's meaningful context to surface; the two shapes can coexist in the same Breakdown block.

For thread directives, Context: must be action-ready. Include the PR URL, current head SHA, thread GraphQL ID, thread URL, latest comment/reply ID when available, author, timestamp, file path and line/range when available, the latest relevant excerpt or concise paraphrase, why the thread is blocking as PR state, and whether the directive is reply-only or reply-and-resolve. For a review body or top-level comment, the same shape without a thread GraphQL ID: review or comment id, URL, author, timestamp, excerpt, why it blocks, and that Suggested: is prose because no review-thread id exists.

Example mixed-shape FAIL:

## check-pr: FAIL
 
Reason: Two threads open; one CI flake.
 
Breakdown:
- Review feedback addressed: FAIL
  Reason: Open human-authored review thread on payment-handler.ts:142 blocks the Review feedback addressed gate.
  Suggested: reply PRRT_kwDOExample
  Context: PR https://github.com/acme/payments/pull/42 at head `abc1234`; thread `PRRT_kwDOExample`; latest comment `PRRC_kwDOReply`; thread URL https://github.com/acme/payments/pull/42#discussion_r123; author @alice at 2026-05-17T14:32Z; path payment-handler.ts line 142; latest excerpt: "What happens when amount is exactly zero? Test missing for the zero-amount branch." Human-authored thread: reply only, leave open.
- CI green: FAIL — retrigger lint-checks

Example unthreaded FAIL (review body — no thread id, so prose that names the outstanding item):

## check-pr: FAIL
 
Reason: Unanswered CHANGES_REQUESTED review body; inline threads are resolved.
 
Breakdown:
- Review feedback addressed: FAIL
  Reason: Unanswered CHANGES_REQUESTED review body from @bob has no review-thread id.
  Suggested: Reply on the pull request Conversation answering the body asks: add changelog entries; show a green test run on the newly supported Python version. No review-thread GraphQL ID exists. Caller judges validity, relevance, and proportionality and composes the public text.
  Context: PR https://github.com/acme/payments/pull/42 at head `abc1234`; review `PRR_kwDOExample`; URL https://github.com/acme/payments/pull/42#pullrequestreview-99; author @bob at 2026-05-17T14:32Z; state CHANGES_REQUESTED; latest excerpt: "Please add changelog entries and show tests passing on Python 3.13." Human-authored; do not emit re-request-review for the unanswered content.

Example mixed FAIL (thread plus body — Suggested is prose naming every outstanding item; thread ids stay in Context):

## check-pr: FAIL
 
Reason: One open thread and an unanswered COMMENTED review body.
 
Breakdown:
- Review feedback addressed: FAIL
  Reason: Open human-authored thread on payment-handler.ts:142 and an unanswered COMMENTED review body from @bob.
  Suggested: Reply on thread PRRT_kwDOExample (leave open) and reply on the Conversation answering the body ask: missing test for the zero-amount branch is also named in the summary. No thread id for the body. Caller judges validity, relevance, and proportionality and composes the public text.
  Context: PR https://github.com/acme/payments/pull/42 at head `abc1234`; thread `PRRT_kwDOExample`; thread URL https://github.com/acme/payments/pull/42#discussion_r123; path payment-handler.ts line 142; review `PRR_kwDOBody`; URL https://github.com/acme/payments/pull/42#pullrequestreview-99; author @bob at 2026-05-17T14:32Z; latest body excerpt: "Also: what happens when amount is exactly zero?"

Example prose-finding FAIL (situation doesn't fit the vocabulary cleanly):

## check-pr: FAIL