/wait-for-pr-checks

name: wait-for-pr-checks
description: >
  Poll a GitHub PR's checks until they all pass, any one fails, or a
  timeout is hit. Returns a structured outcome the caller can gate on.
  TRIGGER when the user says "wait for CI", "wait for the PR checks",
  "watch the PR", "is CI green yet", "babysit this PR's checks",
  "block until checks pass", "/nyann:wait-for-pr-checks".
  Do NOT trigger on "what's the PR status" (that's a one-off
  `gh pr view` — no polling). Do NOT trigger on "merge this PR" —
  that's the action AFTER waiting; consider `/nyann:ship` instead,
  which combines wait + merge.

wait-for-pr-checks

Wraps `bin/wait-for-pr-checks.sh`. Poll-based; uses `gh pr checks <num>` under the hood. The script is the same one `release.sh` will uses to gate the tag step (when `--wait-for-checks` is passed), so the contract is shared.

1. Resolve the PR number

The script auto-resolves from the current branch via `gh pr view`, so the most common invocation is:

bin/wait-for-pr-checks.sh --target <cwd>

Pass `--pr <number>` when watching a PR you don't have checked out.

2. Tune timeout and cadence

Defaults:

• `--timeout 1800` (30 minutes)
• `--interval 30` (poll every 30 seconds)

Bump timeout for slow CI matrices ("integration tests take 90 min" → `--timeout 7200`). Drop interval for snappy local CI ("we Just hit go" → `--interval 10`). Don't go below 10 seconds — gh API rate limits start to bite.

3. Interpret the outcome

The script emits a `PRChecksResult` JSON. Branch on `.outcome`:

| Outcome | Meaning | What the user should do | |---|---|---| | `pass` | every check completed with a passing conclusion | proceed with the gated action (merge, tag, deploy) | | `no-checks` | PR has no checks attached | proceed; treat as pass | | `fail` | at least one check failed (loop bailed early) | open the linked workflow; don't proceed | | `timeout` | deadline reached, some still in_progress | retry with a longer timeout, or investigate slow runners | | `skipped` | gh missing/unauthenticated, or PR couldn't be resolved | tell the user; can't proceed |

Exit code mirrors the outcome: 0 for pass / no-checks / skipped, 3 for fail / timeout — caller scripts can gate on `$?`.

4. Combining with merge

This skill only waits. To wait-then-merge in one step, use `/nyann:ship` — it opens a PR and merges it in one flow (either via GitHub auto-merge or by polling CI client-side). Reserve this skill for cases where the user wants the wait surfaced explicitly (release runs, manual gating).

When to hand off

• "Merge it for me when CI passes" → `/nyann:ship`

(opens a PR and merges it, waiting for CI as needed).

• "I just want the current status, don't wait" → `gh pr checks`

directly; no polling needed.

• "Why did check X fail?" → `gh run view <run-id> --log-failed`;

this skill only reports outcomes, not log contents.