1---
2name: babysit-pr
3description: Monitor a pull request through review and CI. Use when the user asks to monitor, watch, or babysit a PR.
4---
5
6# Babysit PR
7
8Many repos have AI review bots. They're helpful, even if they are not always
9right.
10
11## Waiting
12
13Never write your own watcher, polling loop, or `sleep` loop. Use one watcher
14per PR: `watch_pull_request` in T3 Code, `pr-wait` everywhere else. Never run
15both on the same PR. Every watcher on a GitHub account shares one rate limit.
16
17### In T3 Code: `watch_pull_request`
18
19Handle the existing checks and comments first. Then call
20`watch_pull_request` and end your turn. T3 Code wakes you with a message when
21a check fails, the required checks pass, someone comments or reviews, or the
22branch conflicts.
23
24- **Only the thread that owns the PR watches it.** If you are a delegated
25 child task (a reviewer, a Sol round, any `delegate_task` child), never call
26 `watch_pull_request`. The parent owns the PR. Do not watch PRs you are not
27 working on.
28- **A wake is news, not a merge decision.** Check the merge gate yourself.
29- **Unwatch when you hand off.** A watched thread stays in Working and out of
30 the user's inbox. When you stop (ready, blocked, or asking the user a question),
31 call `unwatch_pull_request` first. A merge or close ends the watch on its
32 own.
33- **"Stopped watching, could not read it"** usually means GitHub's rate limit
34 is used up. Run `gh api rate_limit --jq .resources.graphql` before you
35 watch again. If `remaining` is near 0, wait for `reset` with one background
36 command, then watch again. Never watch again in a tight loop.
37
38### Everywhere else: `pr-wait`
39
40Wait with `scripts/pr-wait` from this skill's directory (use its absolute
41path).
42
43```bash
44pr-wait <pr> [--repo owner/name] [--until ready|green|any-change]
45```
46
47It prints one line per real event. It exits 0 when the `--until` condition is
48met or the PR merges, 1 when it needs you (a required check failed, conflicts,
49unresolved threads, PR closed), and 2 on bad input.
50
51- `ready` (default): required checks green, Greptile or Macroscope reviewed the
52 head, and no unresolved threads. Use this to babysit.
53- `green`: required checks only. Use it when the repo has no Greptile or
54 Macroscope.
55- `any-change`: exit on the first event.
56
57In Claude Code, run it with the Monitor tool (`timeout_ms: 3600000`), so each
58line wakes you. Without a monitor, run it as one long command. It ends on its
59own.
60
61Start it again after you push, after you handle an exit 1, and after a resume.
62It remembers what it already reported, so nothing that arrived in between is
63lost. If it says another pid already watches the PR, do not start a second one.
64Kill the old one only if its events do not reach you.
65
66With either watcher: when an event needs no action, end your turn without a
67message. Never post or say "still waiting".
68
69## GitHub rate limits
70
71`gh pr create`, `gh pr view`, and `gh pr checks` use GraphQL. When GraphQL is
72used up, the REST limit is separate and usually still has room. Use
73`gh api repos/<owner>/<repo>/pulls/<n>` to read a PR, and
74`gh api repos/<owner>/<repo>/commits/<sha>/check-runs` for checks.
75
76## Reviews
77
78Only act on checks and comments newer than the latest push. Verify every bot
79finding against the source before changing code. Fix real findings and CI
80failures, distinguish repository failures from infrastructure flakes, and reply
81with a written reason when dismissing false positives.
82
83If the repo has `.macroscope/check-run-agents/*.md`, read those rules before you
84reply to a Macroscope finding. Its findings cite them.
85
86CodeRabbit is advisory. Treat its findings like any other finding, but never
87wait for it and never hold a merge for it.
88
89If a review bot leaves feedback you believe is not worth addressing, reply with
90a written reason and resolve the comment. Use the `leaving-pr-comments` skill
91for every comment posted on the user's behalf.
92
93Screenshots and videos help as well, when you have a way to upload them.
94
95Keep the PR at the size the user's goal needs. Review loops tend to grow a
96PR one cheap-looking fix at a time. Fix real bugs in the intended case.
97Decline the rest with a written reason, and list them as follow-ups:
98unneeded tests, guards for edge cases that do not matter, extra integration
99or compatibility, and small performance costs. Prefer the fix that deletes or
100narrows code.
101
102## Base branch and merging
103
104Keep an eye on changes to `main` and rebase when needed. `pr-wait` reports when
105new base commits touch this PR's files, and when the PR becomes BEHIND or DIRTY.
106`watch_pull_request` reports conflicts only, so check for BEHIND yourself
107before you call the PR ready.
108If an overlapping PR makes this one obsolete, stop monitoring, report it to the
109user, and ask before closing the PR unless closure was explicitly authorized.
110
111If nothing has changed, stay quiet rather than posting filler comments. Stop
112when `pr-wait` exits 0, or in T3 Code when the merge gate passes on the latest
113head. Merge only when the user explicitly requested it;
114otherwise report that the PR is ready. Right before a merge, run `git fetch` and
115check the PR again. Never merge when it is BEHIND or DIRTY, or when base commits
116that landed after the last green run touch this PR's files. Rebase, push, and
117wait for green again.