improvise/.agents/skills/pr-watch/SKILL.md

name, description

name	description
pr-watch	Wait for a GitHub PR's checks to finish before merging or reporting on it. Use whenever you need to know whether a PR is green. Do not hand-roll a polling loop over gh pr view.

Waiting on a PR

scripts/pr-watch <pr-number> [--expect <sha>] [--timeout <sec>] [--interval <sec>]

exit 0  every check COMPLETED and none failed
exit 1  a check failed, or the PR is CONFLICTING
exit 2  the head moved during the wait, or is not --expect
exit 3  timed out with checks still running
exit 4  usage or environment error

Pass --expect <sha> whenever you know which commit you are asking about. It is the difference between "this PR is green" and "the thing I pushed is green", and a PR here was once merged at a head that predated its own fix.

Do not write the loop yourself

Three signals look like "finished" and are not:

• "nothing pending" — also true when no check has registered yet. Require a non-zero total as well.
• conclusion == null — conclusion is a string, empty while running. Test status == "COMPLETED".
• a verdict from before the head moved — re-check the head, or --expect.

gh is shell-aliased to a different tool in these shells; pr-watch locates a real one itself. Do not reintroduce a bare gh call in a script here.

Before deciding a PR is stuck

Check suites can take several minutes to appear at all, and a Copilot review takes about six. Compare date -u against the GitHub timeline rather than a felt interval, and do not close and reopen a PR to unstick it.

scripts/pr-watch-test.sh drives every case from fixtures.