Babysit PR

PR Babysitter

Objective

Babysit a PR persistently until one of these terminal outcomes occurs:

• The PR is merged or closed.
• A situation requires user help (for example CI infrastructure issues, repeated flaky failures after retry budget is exhausted, permission problems, or ambiguity that cannot be resolved safely).
• Optional handoff milestone: the PR is currently green + mergeable + review-clean. Treat this as a progress state, not a watcher stop, so late-arriving review comments are still surfaced promptly while the PR remains open.

Do not stop merely because a single snapshot returns idle while checks are still pending.

Inputs

Accept any of the following:

• No PR argument: infer the PR from the current branch (--pr auto)
• PR number
• PR URL

Core Workflow

1. When the user asks to "monitor"/"watch"/"babysit" a PR, start with the watcher's continuous mode (--watch) unless you are intentionally doing a one-shot diagnostic snapshot.
2. Run the watcher script to snapshot PR/review/CI state (or consume each streamed snapshot from --watch).
3. Inspect the actions list in the JSON response.
4. If diagnose_ci_failure is present, inspect failed run logs and classify the failure.
5. If the failure is likely caused by the current branch, patch code locally, commit, and push. Do not patch random flaky tests, CI infrastructure, dependency outages, runner issues, or other failures that are unrelated to the branch.
6. If process_review_comment is present, inspect surfaced published review items and decide whether to address them.
7. If a review item is actionable and correct, patch code locally, commit, push, and then resolve the associated review thread only when allowed by the GitHub state mutation policy below.
8. Do not post replies to human-authored review comments/threads unless the user explicitly confirms the exact response. If a human review item is non-actionable, already addressed, or not valid, surface the item and recommended response to the user instead of replying on GitHub.
9. If the failure is likely flaky/unrelated and retry_failed_checks is present, rerun failed jobs with --retry-failed-now.
10. If both actionable review feedback and retry_failed_checks are present, prioritize review feedback first; a new commit will retrigger CI, so avoid rerunning flaky checks on the old SHA unless you intentionally defer the review change.
11. On every loop, look for newly surfaced review feedback before acting on CI failures or mergeability state, then verify mergeability / merge-conflict status (for example via gh pr view) alongside CI.
12. After any push or rerun action, immediately return to step 1 and continue polling on the updated SHA/state.
13. If you had been using --watch before pausing to patch/commit/push, relaunch --watch yourself in the same turn immediately after the push (do not wait for the user to re-invoke the skill).
14. Repeat polling until stop_pr_closed appears or a user-help-required blocker is reached. A green + review-clean + mergeable PR is a progress milestone, not a reason to stop the watcher while the PR is still open.
15. Maintain terminal/session ownership: while babysitting is active, keep consuming watcher output in the same turn; do not leave a detached --watch process running and then end the turn as if monitoring were complete.

Commands

One-shot snapshot

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --once

Continuous watch (JSONL)

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --watch

Trigger flaky retry cycle (only when watcher indicates)

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --retry-failed-now

Explicit PR target

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr <number-or-url> --once

CI Failure Classification

Use gh commands to inspect failed runs before deciding to rerun.

• gh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha
• gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs -X GET -f per_page=100
• gh api repos/<owner>/<repo>/actions/jobs/<job-id>/logs > /tmp/codex-gh-job-<job-id>-logs.zip
• gh run view <run-id> --log-failed as a fallback after the overall workflow run is complete

gh run view --log-failed is workflow-run scoped and may not expose failed-job logs until the overall run finishes. For faster diagnosis, poll the run's jobs first and, as soon as a specific job has failed, fetch that job's logs directly from the Actions job logs endpoint. The watcher includes a failed_jobs list with each failed job's job_id and logs_endpoint when GitHub exposes one.

Prefer treating failures as branch-related when failed-job logs point to changed code (compile/test/lint/typecheck/snapshots/static analysis in touched areas).

Prefer treating failures as flaky/unrelated when logs show transient infra/external issues (timeouts, runner provisioning failures, registry/network outages, GitHub Actions infra errors).

Do not attempt to fix flaky/unrelated failures by changing tests, build scripts, CI configuration, dependency pins, or infrastructure-adjacent code unless the logs clearly connect the failure to the PR branch. For flaky/unrelated failures, rerun only when the watcher recommends retry_failed_checks; otherwise wait or stop for user help.

If classification is ambiguous, perform one manual diagnosis attempt before choosing rerun.

Read .codex/skills/babysit-pr/references/heuristics.md for a concise checklist.

Review Comment Handling

The watcher surfaces review items from:

• PR issue comments
• Inline review comments
• Review submissions (COMMENT / APPROVED / CHANGES_REQUESTED)

Only act on published feedback. Ignore review submissions in GitHub's PENDING state and inline comments attached to those pending reviews. Do not mark pending review feedback as seen; it should be eligible to surface after the reviewer submits the review.

It intentionally surfaces Codex reviewer bot feedback (for example comments/reviews from chatgpt-codex-connector[bot]) in addition to human reviewer feedback. Most unrelated bot noise should still be ignored. For safety, the watcher only auto-surfaces trusted human review authors (for example repo OWNER/MEMBER/COLLABORATOR, plus the authenticated operator) and approved review bots such as Codex. On a fresh watcher state file, existing unaddressed published review feedback may be surfaced immediately (not only comments that arrive after monitoring starts). This is intentional so already-open review comments are not missed.

When you agree with a comment and it is actionable:

1. Patch code locally.
2. Commit with codex: address PR review feedback (#<n>).
3. Push to the PR head branch.
4. After the push succeeds, resolve the associated GitHub review thread only when allowed by the GitHub state mutation policy below.
5. Resume watching on the new SHA immediately (do not stop after reporting the push).
6. If monitoring was running in --watch mode, restart --watch immediately after the push in the same turn; do not wait for the user to ask again.

Do not post replies to human-authored GitHub review comments/threads automatically. If you disagree with a human comment, believe it is non-actionable/already addressed, or need to answer a question, report the item to the user with a suggested response and wait for explicit confirmation before posting anything on GitHub. If the user approves a response, prefix it with [codex] so it is clear the response is automated and not from the human user. If the watcher later surfaces your own approved reply because the authenticated operator is treated as a trusted review author, treat that self-authored item as already handled and do not reply again.