| name | watch-pr |
| description | Monitor CI on a pull request in the background and notify when checks finish or fail fast. Use when the user wants to watch a PR after pushing, get notified about CI failures, or asks to monitor checks. Triggers on: watch the PR, monitor CI, monitor the PR, watch CI, ping me when CI is done, watch checks. |
| user-invocable | true |
Watch PR
Monitor CI on a pull request in the background. When the watch completes (CI passes, fails, or hits an unexpected state), proactively report back to the user. On failure, automatically invoke the ci-analysis skill to surface the relevant test/build failures.
The Job
Delegate the entire "watch, report, investigate" flow to a background sub-agent using a cheap model so premium tokens are not spent on idle waiting or CI failure investigation. The main agent only spends a small dispatch turn at the start and a small surface turn at the end.
The sub-agent runs gh pr checks <pr> --watch --fail-fast --interval 900 and waits for completion. The --interval 900 polls every 15 minutes (low rate-limit footprint, fine for hour-scale CI). The --fail-fast exits on first check failure so the user hears about problems quickly.
When the sub-agent observes the exit, it reports back. On failure, it invokes the ci-analysis skill itself (in cheap-model context) before returning so the main agent receives a ready-to-surface summary.
Token Cost
- Wait phase: Zero model tokens. The sub-agent is idle waiting on the shell command; no thinking happens until the command exits.
- Launch phase (main agent): ~few hundred premium tokens to dispatch.
- Report phase (sub-agent, cheap model): ~few hundred to a few thousand cheap tokens for exit-code interpretation. On failure, additional cheap tokens for
ci-analysis investigation (which is normally the largest cost).
- Surface phase (main agent): ~few hundred premium tokens to relay the sub-agent's summary to the user.
This pushes the bulk of the spend onto the cheap model while keeping the user-facing summary in the main agent's voice.
Resolving the PR
Try in order, without asking the user unless all options fail:
- If the user gave a PR number or URL in the prompt, use it.
- Otherwise, if the current branch has an associated PR, derive it via
gh pr view --json number -q .number.
- Otherwise, ask the user which PR to watch.
When constructing the gh pr checks command, prefer passing the explicit PR number (or URL) rather than relying on branch lookup, so the watch is unambiguous if the user later checks out a different branch.
Launching the Watch
Use the task tool with agent_type: "task" (Haiku-by-default, optimized for "run and report success/failure") and mode: "background". Explicitly set model: "claude-haiku-4.5" (or another cheap model the user prefers) to make the cost intent clear and to override any default that may shift over time.
The sub-agent prompt should:
- Run
gh pr checks <pr> --watch --fail-fast --interval 900 (with --repo if needed)
- Observe the exit code
- On exit
0: return a one-line "CI passed on PR #N" summary
- On exit
1: invoke the ci-analysis skill on the PR URL, then return a concise failure summary (failed leg names, top error excerpts) so the main agent does not need to re-investigate
- On exit
8 or other: return the raw exit code and a short snippet of captured output
Sample dispatch:
agent_type: "task"
mode: "background"
model: "claude-haiku-4.5"
name: "watch-pr-83275"
prompt:
Run `gh pr checks 83275 --repo dotnet/roslyn --watch --fail-fast --interval 900`
in the repo's working directory and wait for it to exit. Then:
- exit 0: respond "CI passed on dotnet/roslyn#83275".
- exit 1: invoke the ci-analysis skill on https://github.com/dotnet/roslyn/pull/83275
and return a concise failure summary (failed leg names, top errors,
whether matched to known issues).
- other: return the exit code and a short tail of stdout/stderr.
After dispatching, briefly tell the user the watch has started, mention the cheap model in use, and end your turn. Do not wait. The completion notification will arrive automatically.
Optional: Detached PowerShell Fallback
If the user explicitly wants the watch to survive a CLI restart (background sub-agents may not), fall back to launching gh pr checks ... --watch ... as a mode: "async" PowerShell command with detach: true. The trade-off: the main agent (premium model) handles the report and any ci-analysis invocation, so failures cost more.
Use this fallback only on explicit user request. The default is the cheap-model sub-agent flow above.
When the Sub-Agent Completes
The completion notification arrives with the sub-agent's final response. Use read_agent with wait: true to retrieve the summary it prepared.
Surface it to the user verbatim or with minimal rephrasing. Do not re-run ci-analysis from the main context — the sub-agent has already done that work in the cheap model and packaged the result.
If the sub-agent reports an unexpected exit code or its summary looks incomplete, then it is reasonable to follow up (send write_agent for a clarification, or run a small targeted investigation in the main context). Otherwise just relay.
Watching Multiple PRs
If the user asks to watch several PRs at once, dispatch one cheap sub-agent per PR. Each completes and notifies independently. Use clearly distinct name values (e.g., watch-pr-83275, watch-pr-83276) so notifications are easy to attribute.
Re-launching After New Commits
If the user pushes a new commit while a watch is running, the previous watch will exit (since the old checks complete) and the new commit's checks will not be watched. That is expected. After reporting the prior result, ask whether to re-launch the watch on the new commit.
Guardrails
- Do not post comments to GitHub on the user's behalf.
- Do not retry or "fix" CI failures unless explicitly asked. The job is to monitor and surface, not to act.
- If
gh is not authenticated, surface the error clearly rather than silently failing.
- When the user is offline or
gh cannot reach GitHub, the watch will exit with a non-zero code. Report this distinctly from a real CI failure.
Completion Checklist
Before considering the initial launch turn done:
When the notification arrives:
