--- name: pr-babysit version: 1.0.0 description: Watch one pull request through CI and review until it is ready, with one event-driven watcher and no polling. Use for "babysit this PR" or "watch this PR until green". Do NOT use for many PRs (use pr-autofix) or thread replies (use pr-comment-responder). license: MIT argument-hint: " [--until ready|green|any-change]" user-invocable: true metadata: source_pattern: t3dotgg/tstack babysit-pr (MIT) capability: kind: orchestrator depends-on: [review-conversation, review-thread-closure] status: active routing: role: front-door invoker: autoplan trigger: autoplan's long-tail resolver matches a request to watch or babysit one PR user-facing: true intents: - babysit pr - babysit this pr - watch pr - watch this pr - monitor pr - wait for checks - wait for ci - wait for review --- # PR Babysit Watch one pull request from push to ready. Handle each real event (a failed check, a new review, a conflict) and stay quiet between events. Review bots help, but they are not always right. Adapted from `t3dotgg/tstack` `babysit-pr` (MIT). This port routes GitHub reads through the github skill and `github_core`, not raw `gh`, and replies through `pr-comment-responder`. ## Triggers `babysit this PR`, `watch this PR`, `monitor this PR until green`, `wait for checks and reviews` ## Process ### Phase 1: Handle what already exists Read the current checks and review threads on the head. Fix real failures and work threads with `pr-comment-responder` before you start a watcher. ### Phase 2: Wait for the next event Never write your own watcher, polling loop, or `sleep` loop. Use one watcher per PR. Never run two watchers on the same PR: every watcher on a GitHub account shares one rate limit. #### When `watch_pull_request` is available (T3 Code) Handle the existing checks and comments first. Then call `watch_pull_request` with the full PR URL and end your turn. T3 Code wakes you when a check fails, the required checks pass, someone comments or reviews, or the branch conflicts. - **Only the thread that owns the PR watches it.** A delegated child (a reviewer, any `delegate_task` child) never calls `watch_pull_request`. The parent owns the PR. Do not watch a PR you are not working on. - **A wake is news, not a merge decision.** Check the merge gate yourself. - **Unwatch when you hand off.** A watched thread stays in Working. Before you stop (ready, blocked, or asking the user), call `unwatch_pull_request`. A merge or close ends the watch on its own. - **"Stopped watching, could not read it"** usually means the GitHub rate limit is spent. Check it before you watch again (see GitHub rate limits). Never re-watch in a tight loop. - `watch_pull_request` reports conflicts, not BEHIND. Check for BEHIND yourself before you call the PR ready. #### Everywhere else: `pr_wait.py` Run `pr_wait.py` (see Scripts) under the host's native wait tool: **Waiting on each host.** "Wait on a long-running command" means the host's background-run tool, so each output line wakes you and nothing polls. Claude Code: `Monitor` with the command and `timeout_ms: 1800000` (its cap), so each stdout line arrives as an event; re-arm it when it expires. For one completion notice, `Bash` with `run_in_background: true` instead. T3 Code: `t3_background_wait` with the task ID of a background command. Codex: `exec_command` with a long `yield_time_ms`, then `write_stdin` with empty `chars` to wait for more output. Copilot CLI: `bash` (or `powershell` on Windows), then `read_bash` (`read_powershell`) for more output. Devin CLI: `exec`, then `get_output`. Antigravity: `run_command`. Factory Droid: `Execute`. Muse Code documents no background shell tool. On Muse Code, or any host not named here, run the command in the foreground as one long call and read its output when it returns. Never write a `sleep` loop, and never call a status command over and over to wait. Start the watcher again after you push, after you handle an exit 1, and after a resume. It keeps state per PR for 6 hours, so a restarted watcher reports what arrived while none ran. A blocker it already reported (for example a thread only the reviewer can resolve) does not exit again: the watcher waits for it to clear. A first run, or a run after a longer gap, reports the current check and merge state and only newer comments. A host that cannot stream lines from a background command never sees events until the command ends. There, run with `--until any-change` so each event ends the run. With either watcher: when an event needs no action, end your turn without a message. Never post or say "still waiting". ### Phase 3: Act on each event Each event gets a fix, a written reason, or no action. Then return to Phase 2. The sections below govern this phase. ## GitHub rate limits GraphQL and REST have separate budgets. When GraphQL is spent, the github skill's `get_pr_checks.py` falls back to REST for checks on its own. Read the remaining budget with the github skill before you watch again; never guess a reset time. If GraphQL is near zero, wait for its reset with one background command (see Waiting on each host), then start one watcher. ## Reviews Only act on checks and comments newer than the latest push. Verify every bot finding against the source before you change code. Fix real findings and CI failures. Tell repository failures apart from infrastructure flakes; rerun a flake with the github skill's `rerun_failed_jobs.py`. Work review threads with the `pr-comment-responder` skill. It owns the in-thread reply, the written reason for a dismissed finding, and thread resolution. Do not post review replies by hand. Treat advisory bots (for example CodeRabbit) like any other reviewer, but never wait for them and never hold a merge for them. Keep the PR at the size the user's goal needs. Review loops grow a PR one cheap-looking fix at a time. Fix real bugs in the intended case. Decline the rest with a written reason and list them as follow-ups: unneeded tests, guards for edge cases that do not matter, extra compatibility, and small performance costs. Prefer the fix that deletes or narrows code. ## Base branch and merging Watch for base changes and update the branch when needed. `pr_wait.py` reports `base` when the base moves and `merge-state` when the PR turns BEHIND or DIRTY. Update with the github skill's `update_pr_branch.py`, or merge the base locally; never force-push a shared branch. If an overlapping PR makes this one obsolete, stop watching, tell the user, and ask before you close it unless closing was authorized. The merge gate is the github skill's `test_pr_merge_ready.py` on the latest head. A watcher exit 0 or a T3 Code wake is the cue to run it, not a pass. Stop when that gate passes. Merge only when the user asked for it; otherwise report that the PR is ready. Right before a merge, fetch and check the PR again. Never merge when it is BEHIND or DIRTY, or when base commits that landed after the last green run touch this PR's files. Update, push, and wait for green again. ## Scripts ### `pr_wait.py` Run the watcher through the plugin locator: ```bash ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/pr-babysit/scripts/pr_wait.py --until ready; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 ) ``` `` is a PR number or URL. Add `--repo owner/name` when the checkout is not the PR's repository. It prints one line per real event (`head`, `check`, `green`, `comment`, `review`, `thread`, `activity`, `base`, `merge-state`, `ready`, `blocked`, `merged`, `closed`) and nothing else on stdout, except one `unreachable:` line right before exit 3. Every exit 1 prints a `blocked:` or `closed` line first, and a ready exit 0 prints a `ready:` line. `--help` lists the exit codes. Exit codes: | Exit | Meaning | Next step | |------|---------|-----------| | 0 | `--until` condition met, or the PR merged | Recheck the merge gate on the current head | | 1 | A new blocker: a required check failed or never reported, DIRTY, closed, or (ready) unresolved threads, BEHIND, draft, a required review, or changes requested | Act, push, then start the watcher again | | 2 | Bad input, PR not found, another `pr_wait.py` already watches this PR, `gh` not on PATH, or a `why_pr_blocked.py` payload missing a key | Fix the input; do not start a second watcher; report a payload break | | 3 | GitHub stayed unreachable for 10 polls in a row | Check the rate limit, then start again | | 4 | `gh` is not authenticated | Sign in to `gh`, then start again | `--until`: `ready` (default) needs required checks green, no unresolved thread, no required or changes-requested review, and a branch that is not BEHIND, DIRTY, or a draft. It also waits 3 minutes after the watcher first sees a head, a heuristic: review bots tend to post 30 to 120 seconds after a push. A blocker only a person can clear (a required review, a reviewer's thread) exits 1 once, then the restarted watcher waits for it quietly, across pushes, until a green poll shows it cleared. A required check counts as never reported only 45 minutes after the watcher first saw the head. `green` needs required checks only. `any-change` applies the `ready` rules and also exits on the first event. The gate reads required checks from the base-branch ruleset through `why_pr_blocked.py`, so it matches what branch protection enforces. The watcher sees the newest 100 review threads. On a PR with more, it says so once; read every thread with `pr-comment-responder` before you call it ready. ## Anti-Patterns - A `sleep` loop or a repeated `gh pr checks` call instead of one watcher. - Two watchers on one PR, or a delegated child watching the parent's PR. - Posting "still waiting" comments or chat messages between events. - Merging because a watcher exited 0, without rereading the current head. ## Verification - [ ] One watcher ran per PR, with no `sleep` loop or repeated status calls. - [ ] Every failed check and review thread got a fix or a written reason. - [ ] The final state was read on the current head, not a cached event. - [ ] (T3 Code) `unwatch_pull_request` ran before handoff.