do-github-pr-sentinel

name	do-github-pr-sentinel
description	Monitor a GitHub pull request until it's merged, green, or blocked. Polls CI checks, review comments, and mergeability state continuously. Diagnoses failures, retries flaky checks up to 3 times, auto-fixes branch-related issues when possible, and stops only when user help is required. Use when asked to "monitor a PR", "watch CI", "handle review comments", "sentinel a PR", or keep an eye on failures and feedback.
compatibility	Any CLI agent (OpenCode, Claude, Codex, Cursor, etc.)
metadata	{"source":"https://github.com/openai/codex/tree/main/.codex/skills/babysit-pr","version":"1.0.0"}

PR Sentinel

Monitor a GitHub pull request persistently until one of these terminal outcomes occurs.

Terminal Outcomes (stop when any is true)

• PR merged or closed — stop immediately on confirmation.
• PR ready to merge — CI green, no unaddressed review comments, not blocked on required review approval, no merge conflict risk.
• User help required — CI infrastructure issues, exhausted flaky retries (3 cycles), permission problems, or ambiguous situations that cannot be resolved safely.

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

Inputs

Accept any of:

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

Core Workflow

1. When asked to "monitor"/"watch"/"babysit" a PR, start with --watch (continuous mode) unless doing a one-shot diagnostic.
2. Run the watcher script to snapshot PR/CI/review state.
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 branch-related: patch code locally, commit, and push.
6. If process_review_comment is present, inspect surfaced review items and decide whether to address them.
7. If a review item is actionable and correct, patch code locally, commit, and push.
8. If likely flaky/unrelated and retry_failed_checks is present, rerun failed jobs with --retry-failed-now.
9. If both actionable review feedback and retry_failed_checks are present, prioritize review feedback first — a new commit retriggers CI, so avoid rerunning flaky checks on the old SHA.
10. On every loop, verify mergeability / merge-conflict status (e.g. via gh pr view).
11. After any push or rerun, immediately return to step 1 and continue polling on the updated SHA.
12. If you paused --watch to patch/commit/push, relaunch --watch yourself in the same turn after the push.
13. Repeat polling until the PR is green + review-clean + mergeable, stop_pr_closed appears, or a user-help-required blocker is reached.
14. Keep consuming watcher output in the same turn while babysitting is active — do not end the turn with a detached --watch process.

Commands

One-shot snapshot

python3 .agents/skills/do-github-pr-sentinel/scripts/gh_pr_watch.py --pr auto --once

Continuous watch (JSONL)

python3 .agents/skills/do-github-pr-sentinel/scripts/gh_pr_watch.py --pr auto --watch

Trigger flaky retry cycle

python3 .agents/skills/do-github-pr-sentinel/scripts/gh_pr_watch.py --pr auto --retry-failed-now

Explicit PR target

python3 .agents/skills/do-github-pr-sentinel/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 run view <run-id> --log-failed

Branch-related — logs point to changed code (compile/test/lint/typecheck in touched areas):

• Patch code locally, commit with conventional format, push.

Flaky/unrelated — transient infra issues (timeouts, runner failures, registry outages, rate limits):

• Rerun failed jobs.

Ambiguous — do one manual diagnosis attempt before choosing rerun.

See references/heuristics.md for the full checklist.

Review Comment Handling

The watcher surfaces review items from:

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

It surfaces feedback from trusted human reviewers (repo OWNER/MEMBER/COLLABORATOR + authenticated operator) and approved review bots.

On a fresh state file, existing pending review feedback is surfaced immediately (not only new comments after monitoring starts).

When a comment is actionable and correct

1. Patch code locally.
2. Commit: fix: address PR review feedback (#<n>)
3. Push to the PR head branch.
4. Resume watching on the new SHA immediately — do not stop after reporting the push.
5. If monitoring was in --watch mode, restart --watch immediately after the push.

When a comment is non-actionable

• Already resolved in GitHub → safely ignore.
• Ambiguous → record as handled, continue polling.
• Conflicts with user intent → stop and ask.

Git Safety Rules

• Work only on the PR head branch.
• Avoid destructive git commands.
• Do not switch branches unless necessary to recover context.
• Before editing, check for unrelated uncommitted changes. If present, stop and ask the user.
• After each fix, commit and git push, then re-run the watcher.
• If you interrupted --watch to fix, restart --watch immediately after the push.
• Do not run multiple concurrent --watch processes for the same PR.
• A push is not a terminal outcome — continue monitoring unless a strict stop condition is met.
• Git failure recovery: If any git command fails, follow the retry sequence in AGENTS.md § Agent Guidance: stash → abort rebase → abort merge → fetch main → retry. Never retry more than 3 times.
• Before CI fixes: Always run gh run list --limit 5 --json conclusion,headBranch,workflowName to diagnose the latest failing runs. Fix the simplest failure first, commit, push, and wait for green before moving to the next. See AGENTS.md § CI Fix Workflow.

Commit message format

• fix: fix CI failure on PR #<n>
• fix: address PR review feedback (#<n>)

Monitoring Loop Pattern

1. Run --once.
2. Read actions.
3. Check if PR is merged/closed — if so, report terminal state and stop.
4. Check CI summary, new review items, mergeability/conflict status.
5. Diagnose CI failures; classify branch-related vs flaky.
6. Process actionable review comments before flaky reruns when both are present.
7. Retry failed checks only when retry_failed_checks is present and you are not about to replace the current SHA.
8. If you pushed a commit or triggered a rerun, report briefly and continue polling.
9. After a review-fix push, proactively restart --watch in the same turn.
10. If everything is passing, mergeable, no unaddressed reviews, and not blocked on approval — report success and stop.
11. If blocked on user-help issue — report the blocker and stop.
12. Otherwise sleep per polling cadence and repeat.

Preferring --watch

When the user asks to monitor/watch/babysit a PR, use --watch for autonomous polling. Use --once only for debugging or one-shot checks.

Do not stop to ask whether to continue — poll autonomously until a strict stop condition or explicit user interruption.

Polling Cadence (Adaptive)

• CI not green: poll every 1 minute.
• CI green: start at 1 min, back off exponentially on no change (1m → 2m → 4m → 8m → 16m → 32m), cap at 1 hour.
• Reset to 1 min whenever anything changes (new SHA, check status change, new review, mergeability change).
• CI regresses (new commit, rerun failure): return to 1-minute polling.
• PR merged/closed: stop immediately.

Stop Conditions (Strict)

Stop only when:

Condition	Action
PR merged or closed	Stop immediately
PR ready to merge (green + review-clean + mergeable)	Report success, stop
User intervention required (infra outage, exhausted retries, permissions)	Report blocker, stop

Keep polling when:

• actions contains only idle but checks are still pending.
• CI is still running/queued.
• Review state is quiet but CI is not terminal.
• CI is green but mergeability is unknown/pending.
• CI is green and mergeable but waiting on review approval.
• CI is green but merge-conflict risk may change.

Output Expectations

During monitoring

• Concise progress updates on status changes only.
• Occasional heartbeat during long unchanged periods.
• Push confirmations, intermediate CI snapshots, and review-action updates are progress only — not final.

CI green celebration

One-time when CI first transitions to all green:

🚀 CI is all green! 33/33 passed. Still on watch for review approval.

Final summary (when a stop condition is met)

Include:

• Final PR SHA
• CI status summary
• Mergeability / conflict status
• Fixes pushed
• Flaky retry cycles used
• Remaining unresolved failures or review comments

References

• CI/Review Heuristics — decision tree for fix vs rerun vs stop
• GitHub CLI API Notes — commands and endpoints used by the watcher

Related Skills

• do-wdr-issue-swarm: Parallel GitHub issue implementation
• do-wdr-release: Release management and versioning