babysit-prs

/babysit-prs — Orchestrator PR Merge Loop

Read .claude/project-config.json. Extract git.defaultBase (PRs polled here) and git.hotfixBase (PRs here require human merge).

Subagents can't poll CI — they're one-shot. After a subagent runs /ship-pr and hands off, someone must handle the merge. That's this skill, run by the main session.

Three use cases per .claude/rules/agent-autonomy.md:

1. Subagent-produced PRs (most common): Task() subagent → /ship-pr → SendMessage handoff → main session runs /babysit-prs.
2. Multi-agent fan-out: N parallel subagents, each producing a PR. One polling loop.
3. Recovery from prior session: previous run ended before push reached merge state.

Single-agent main-session work uses /ship-pr Phase 6.6 autonomous merge — no /babysit-prs needed.

When NOT to invoke

• Single-agent main-session work (use Phase 6.6 instead)
• Hotfix PRs targeting $hotfixBase (human merge per release-flow.md)
• About to end the session (leave open PRs for next orchestrator)

Workflow

Phase 1: Survey

1. gh pr list --base $defaultBase --state open --json number,title,headRefName,updatedAt,mergeStateStatus
2. Classify each:
   • state=MERGED → skip
   • state=OPEN + mergeStateStatus=CLEAN → ready to merge
   • OPEN + UNSTABLE → CI/checks in flight; inspect via gh pr view {N} --json reviews,comments (often = required-check missing rather than failed)
   • OPEN + BLOCKED → real CI failure or missing approval
   • OPEN + DIRTY → merge conflict; needs rebase
   • OPEN + UNKNOWN → recheck in 30s
3. Report one-line summary per PR.

Phase 2: Merge sweep

For each PR at CLEAN (or UNSTABLE-but-ready per latest review verdict):

1. Verify review state via gh pr view {N} --json comments — latest claude author comment. Positive verdicts: "ship-ready", "ship as-is", "no BLOCKERs", "all checks pass", "Self-Review PASSED", "verdict: green", or 🟢. If BLOCKERs surfaced → Phase 2b.
2. Read PR body for Monday task ID: gh pr view {N} --json body | grep "Monday\.com Task".
3. Merge: gh pr merge {N} --admin --squash. NEVER --delete-branch — gh tries to delete the local tracking branch by switching cwd's checkout to $defaultBase, which fails with fatal: '$defaultBase' is already used by worktree and can corrupt the active task's branch state in a worktree session.
4. Local cleanup: git fetch --prune origin. Drops the stale ref. Safe from any worktree.
5. Capture merge SHA: gh pr view {N} --json mergeCommit --jq .mergeCommit.oid.

Phase 2b: Handling BLOCKER findings

Triage per finding:

Finding	Action
<10 lines, low-risk, single-file	Inline fix from orchestrator in .claude/worktrees/feat-<slug>/
Multi-file, requires tests, or > ~30min	Spawn fixup subagent via Agent({ run_in_background: true }) with surgical brief
Genuinely incorrect Claude verdict	Decline via gh pr comment {N} --body ...
Architectural — needs human input	TASK_STUCK + SendMessage user OR file retro

Inline-fix flow: cd to worktree → edit → quick sanity check → git add . && git commit -m "fix: address round-N BLOCKER — <summary>" → git push → re-arm Phase 6 Monitor for round N+1.

Fixup subagent: write a surgical prompt naming the worktree path, branch, PR, the BLOCKER excerpt, the fix directive, and standard rules (no /pickup-task, no merge, no full /ship-pr cycle — just fix + push + report). Spawn with Agent({ subagent_type: 'general-purpose', run_in_background: true }). Estimate 5–15 min.

After fixup pushes, re-arm Phase 6 Monitor for round N+1. Loop terminates when round-K is READY.

Phase 3: Monday reconciliation

For each freshly-merged PR (if MCP up):

1. getTask({ itemId: taskId, format: "json" }) — read state.
2. If sprints lacks active sprint: updateTask({ itemId, sprintId: <active> }) (via listSprints({ activeOnly: true })).
3. Set missing links: updateTask({ itemId, prLink, branch, githubLink, demoUrl }).
4. If parent status not Waiting for UAT:
   • Missing UAT doc → createTaskUatDoc({ taskId, markdown }) from PR body + AC
   • Flip subtasks Done via manageSubtasks({ parentItemId, operations }) with actualHours
   • Monday automation auto-flips parent when all subtasks Done
5. Post createUpdate({ itemId, body: HTML }) summarizing merge.

MCP down: capture state inline as checklist; defer reconciliation; catch up immediately on recovery.

Phase 4: Worktree cleanup

For each merged PR:

1. Worktree path: branch.replace('/', '-') → .claude/worktrees/feat-<slug>
2. git worktree remove --force <path> (--force because remote branch deleted by merge)
3. git branch -D <branch>

Batch: bash .claude/scripts/worktree-audit.sh --remove -y cleans every DONE worktree.

Phase 5: Agent shutdown

For each subagent whose PR merged: SendMessage({ to: <agent>, message: { type: "shutdown_request", reason: "PR #{N} merged at {time}. Work complete." } }).

Phase 6: Continue or exit

More PRs/subagents pending → stay. Queue empty + no agents working → end session.

Polling pattern

Use a Monitor that evaluates current state on first iteration (so an already-posted verdict is matched immediately) and continues watching for new comments. Match either the ship-ready predicates (READY → orchestrator merges) or BLOCKER predicates (BLOCKER → fix inline or send back). Also break on state=MERGED. Set last_seen="" on init — seeding it with the current latest makes the Monitor watch for a SECOND comment that may never come.

A wait condition that ignores current state and only watches future events is broken — always evaluate current state on first iteration. Don't wait for mergeStateStatus=CLEAN — it can be permanently UNSTABLE from secondary workflow noise.

See plugin/rules/monitor-predicate-pattern.md for the two patterns that govern Monitor emission cadence (transition-only) + post-success action timing (act in the same response — don't narrate between Monitor returning and the merge call).

Anti-patterns

• DO NOT use gh pr merge --auto — flaky against this repo's CI (UNSTABLE noise blocks auto-merge). Use --admin --squash.
• DO NOT merge PRs targeting main — hotfix PRs require human merge.
• DO NOT delete the worktree before merging — git refuses (branch checked out).
• DO NOT skip Monday reconciliation if MCP up — post-merge state is the audit trail.
• DO NOT batch reconciliation across MCP outage windows — catch up immediately on recovery.

Failure modes

Symptom	Cause	Fix
gh pr merge "branch is checked out"	Worktree still has the branch	Force-remove worktree, then merge with admin
"PR already merged"	Status update lag from prior tick	Verify via gh pr view --json state; skip to reconciliation if MERGED
updateTask 404 on subtask IDs	Subtasks on different board	Use manageSubtasks({ parentItemId, operations })
Monday MCP "Server not found"	OAuth session switched	Defer; capture queue inline; retry on MCP recovery
CLEAN but --admin fails	Branch protection requires a check the agent didn't see	Check gh pr checks {N} for blocker; add via PR body edit

Output

Keep status lines short:

Sweeping PR queue (N open targeting staging):
  #283 feat/foo — CLEAN → merging
  #285 feat/bar — UNSTABLE (claude-review pending) → skipping
  #286 feat/baz — DIRTY (conflict) → escalating

Merged: #283 at {SHA}, Monday #2915513137 → Waiting for UAT
Next sweep: 5min, or when agent notifies

Cross-references

• /ship-pr Phase 6.6 — main-session autonomous merge
• .claude/rules/release-flow.md — branching + merge policy
• .claude/rules/task-lifecycle.md — status transitions
• .claude/scripts/worktree-audit.sh — batch worktree cleanup