github-pr-sentinel

name	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. Use this skill when the user asks to monitor a PR, watch CI, handle review comments, sentinel a PR, babysit a PR, or keep an eye on failures and feedback — even if they just say "check on the PR" or "is it green yet".

PR Sentinel

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

When to Use

• User asks to monitor a PR, watch CI, or babysit a pull request
• Need to handle review comments or keep an eye on failures and feedback

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/github-pr-sentinel/scripts/gh_pr_watch.py --pr auto --once

# Continuous watch (JSONL)
python3 .agents/skills/github-pr-sentinel/scripts/gh_pr_watch.py --pr auto --watch

# Trigger flaky retry cycle
python3 .agents/skills/github-pr-sentinel/scripts/gh_pr_watch.py --pr auto --retry-failed-now

# Explicit PR target
python3 .agents/skills/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.

Non-conventional commit subjects — the failed job is commitlint and the log shows header-max-length, type-empty, subject-empty, or subject-full-stop. Common with bot-authored PRs (google-labs-jules[bot], dependabot[bot], github-copilot[bot]). See ADR-008 and PR #505 run 27086771117.

• Run .agents/skills/jules-delegator/scripts/normalize-commits.sh --from <base> --to HEAD --type <type> --scope <scope> to rewrite the subjects in place.
• For bots other than Jules, derive a generic prefix: --type chore --scope <area>.
• git push --force-with-lease to the PR head branch.
• Resume --watch on the new head SHA — the commitlint job will re-run.

Non-conventional PR titles — the failed job is lint-pr-title (see ADR-008).

• Rename the PR title immediately using a safe fallback: gh pr edit --title "chore: <original title truncated>".
• Use feat: or fix: only if the branch name or content provides a high-confidence signal.
• Record the rename in .agents/metrics.jsonl per Post-Task Protocol.
• Run --once to confirm lint-pr-title re-triggers, then resume --watch.

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.
• 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.

Commit message format

• fix: fix CI failure on PR #<n>
• fix: address PR review feedback (#<n>)
• chore(commit): normalize bot commits to conventional format

Monitoring Loop Pattern

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

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

See Also

• git-github-workflow — Full commit-to-merge lifecycle
• cicd-pipeline — CI/CD pipeline design and troubleshooting

Rationalizations

Rationalization	Reality
"CI is just being flaky, I'll just merge it"	Flakiness masks real bugs. Rerun or fix, never ignore.
"A human will review this anyway, I don't need to be perfect"	The sentinel's job is to save human reviewers time by catching low-hanging fruit.
"This PR is small, I can skip the full monitoring loop"	Small PRs can have big impacts. Consistency is key to reliability.

Red Flags

• Stopping the monitoring loop before a terminal outcome is reached
• Ignoring actionable review feedback in favor of automated checks
• Rerunning failed checks more than 3 times without diagnosing the root cause

References

• references/heuristics.md - CI/Review decision tree
• references/github-api-notes.md - GitHub CLI commands used by the watcher