assessing-pr-readiness

The job an agent actually has when it looks at a branch or PR is not "is CI green?" — it's what's actionable right now, and what should happen next? That spans CI, reviews, merge state, and open threads. This skill is how to gather those signals cheaply and turn them into a decision.

When to use this

Fire when any of these are true:

• You've pushed and want to know what (if anything) is blocking the PR — "is this ready?", "what's left?", "can I merge?".
• You're picking work back up on a branch and need its current state.
• A long CI run is in flight and you want to wait for it without burning context on polling output.

The signals — and how to read each

Gather these for the branch/PR (most blocking first). Don't stop at CI; a green PR with changes requested is not ready.

• CI status — are checks passing, failing, or still running? A failure is the top priority; a pending run may just need waiting out.
• Review state — CHANGES_REQUESTED blocks; APPROVED clears; empty means review hasn't happened (a comment-only review leaves it empty — read the comments).
• Merge state — conflicts with the base (DIRTY/behind), draft status, or branch protection not satisfied.
• Unresolved threads — review comments left open, even on an approved PR, are usually action items.

How to gather them

One PR-level read covers most of it:

gh pr view <pr-or-branch> --json state,isDraft,reviewDecision,mergeStateStatus,statusCheckRollup,reviewRequests
gh pr checks <pr>                 # per-check pass/fail with links

For a branch with no PR yet, read CI directly:

gh run list --branch <branch> --limit 20 --json databaseId,name,status,conclusion,event

Filter to the most recent run per workflow (several can run on one push; you want the latest of each). If there are zero runs, say CI isn't set up and move on.

Watching in-flight CI to completion

When a run is still going and the point is to wait:

• Prefer gh run watch <run-id> — it streams progress without dumping logs into context. Watch multiple in-flight runs in parallel.
• If gh run watch isn't available, poll gh run view <id> --json status,conclusion — but no faster than once every 30 seconds; faster burns API quota and context cache for nothing.
• For a recurring check rather than a one-shot wait, suggest the /loop skill (e.g. /loop 5m) instead of a tight poll.

For any failure, pull just the failing job's tail (gh run view <id> --log-failed) and extract the actual error — don't paste the whole log; cite the URL for the rest.

Turning state into the next action

State	Next action
CI failing	Read the failing log tail, find the real error, fix. Don't auto-rerun without being asked.
CI pending	Watch to completion (above); report when done.
Changes requested / open threads	Address the findings (see [[receiving-code-review]]); don't merge over them.
Merge conflict / behind base	Rebase or merge the base in; resolve, re-push.
Draft	It's not up for review yet — mark ready only when it is.
Approved + green + clean + threads resolved	It's ready. Surface that; merging is a separate, confirmed action.

Report the state as a short summary plus the single most important next action — not a wall of check output.

Foot-guns

• Stopping at CI. Green checks with changes-requested, conflicts, or open threads is not "ready". Read all four signals.
• Polling too fast. Sub-30s polling for a multi-minute run. Use gh run watch, or /loop for recurring checks.
• Dumping logs. Pasting an entire failing log. Extract the error, link the rest.
• Acting on shared state unprompted. Re-running CI, merging, or marking ready without being asked. Surface the state and the recommended action; let the user pull the trigger on anything outward-facing.
• Treating an empty reviewDecision as "no feedback". A comment-only review leaves it empty — read the comments before concluding nothing's there.