PR Babysitter

PR Babysitter

• IS: keeping one open PR moving: conflicts, CI across GitHub Actions/Buildkite/Vercel/Fly.io, inbound review comments, and merge readiness, as a background monitor or as one-shot fixes.
• IS NOT: opening or editing the PR (pr-creator), reviewing or fixing the diff itself (tidy), or npm release PRs (autoship watches its own release CI; never babysit a release or Version Packages PR it drives).

Mode Selection

Standing rules, every mode:

• Monitoring or fixing code does not by itself authorize posting replies. Post, resolve threads, or request reviews only when the user authorized that communication; otherwise prepare replies and report them.

• Resolve scripts/fetch-comments.sh relative to this installed SKILL.md. ${CLAUDE_SKILL_DIR} below is a Claude Code adapter, not a portable environment variable.

• No setup questions. Auto-detect the PR, the CI platforms, and the defaults (poll every 2 minutes, auto-resolve noise, no auto-merge), then start. Overrides arrive inline: "poll every 5 minutes", "enable auto-merge".

• Skip closed or merged PRs. Skip drafts (isDraft) unless asked.

• Comment triage runs autonomously; the plan file is an audit trail, not an approval gate.

• Speak only on transitions. A quiet poll says nothing.

Reference Files

Monitor Loop

Phase 1 runs once in the foreground and starts the watch. Every event or tick then runs phases 2-5, diffs against the state file, and speaks only when something changed.

Copy this checklist to track progress:

PR babysit progress:
- [ ] Phase 1: Initialize (detect PR, pick watch mechanism, snapshot state)
- [ ] Phase 2: Conflict check
- [ ] Phase 3: CI check (diagnose, fix, gate, push)
- [ ] Phase 4: Comment check (triage new comments)
- [ ] Phase 5: Readiness check (report transitions, write state file)

Phase 1: Initialize

1. gh pr view [N] --json number,url,title,state,isDraft,headRefName,baseRefName,headRefOid,mergeable,mergeStateStatus,reviewDecision. No PR for the branch: say so and stop.
2. gh repo view --json owner,name for the calls that need owner/repo.
3. Detect CI platforms from gh pr checks --json name,link (pattern table in references/ci-platforms.md).
4. Pick the watch mechanism: the first rung of the watch ladder in references/monitoring-setup.md that applies (harness PR subscription, Monitor tool, cron, none). With no rung, do not claim monitor mode: run the matching one-shot mode or say this runtime cannot keep polling.
5. Snapshot state to .claude/pr-babysitter/babysit-pr-{N}.md: mechanism and ID, head SHA, mergeability, check states, open and awaiting-reply thread counts, review decision. This folder is never staged.
6. Confirm in five lines: PR, watch mechanism and ID, detected CI, current state, defaults in effect.

Phase 2: Conflict Check

gh pr view --json mergeable,mergeStateStatus. DIRTY resolves; BEHIND updates; UNKNOWN means GitHub is still computing, recheck next tick; anything else moves on.

git fetch origin {base} && git rebase origin/{base}
git push --force-with-lease --force-if-includes

• Clean rebase: push, notify.
• Conflicts only in lockfiles, generated files, or changelogs: regenerate per the reference, continue the rebase, push.
• Conflicts in source logic, migrations, or API contracts: git rebase --abort, then notify with the files and what each side changed. Human intent decides those.

Bare --force is never used. A refused lease means someone else pushed: abort and notify rather than overwrite their commits. More than one author on the branch means a rebase rewrites their commits: merge origin/{base} instead.

Phase 3: CI Check

1. gh pr checks --json name,state,bucket,link,workflow. bucket is pass, fail, pending, skipping, or cancel; link is the details URL.
2. Anything pending: wait. Diagnosing a half-finished run fixes the wrong thing.
3. Every fail: fetch logs with the platform's commands in references/ci-platforms.md (GitHub Actions, Buildkite auth chain, Vercel, Fly.io).
4. Classify per the reference: flaky (re-run once), stale dependency (reinstall and rebuild before touching source), code error (fix), knip (delete dead code or configure), infrastructure (notify; not fixable from code).
5. Fix, run the verification gate, commit, push. Flag regressions against the previous state (was passing, now failing).

One-shot loop ("fix CI"): after each push, gh pr checks --watch --fail-fast (exit 0 green, 1 a check failed, 8 still pending). Stop and summarize when checks are green, the failure is infrastructure, or the same check fails twice with the same error after a fix. Two identical failures is the signal to stop pushing, not to try a third variant.

Phase 4: Comment Check

1. Count open threads and threads awaiting my reply (newest comment not mine, in any resolution state, minus a reviewer who resolved their own last comment).
2. Compare both counts and the newest updated_at across review and issue comments against the state file. An edited-in-place bot comment and a reply on a resolved thread both have to register.
3. Any increase: notify "N new review comments on PR #{N}" and run the Comment Triage Workflow.

Phase 5: Readiness Check

1. Ready means all of: mergeable == MERGEABLE, every required check pass, reviewDecision == APPROVED from a review whose commit_id is the head SHA, zero open blocking threads, zero threads awaiting my reply, every merge gate satisfied.
2. A merge-gate comment reading "Human review required" is a blocker to report with the criteria that forced it, not a finding to fix.
3. Ready: notify "PR #{N} is ready to merge." Merge is a one-way door: gh pr merge --auto with the repo's merge method, and only when the user opted in.
4. Not ready: name the blockers ("Waiting on: 2 checks pending", "Awaiting your answer: 2 questions from @reviewer", "Approval is stale: reviewed abc1234, head def5678").
5. Write the state file for the next tick.

Comment Triage Workflow

Inline from Phase 4 or one-shot. Autonomous: no approval gate, the plan file is the audit trail.