pr-monitoring

PR Monitoring

Overview

Open is not landed. Green is not merged. A PR you opened is unfinished work until it has actually merged with nothing outstanding — or you have named a blocker only a human can clear. You are the machine that keeps watching so a human doesn't have to babysit the PR; declaring "done" at PR-open (or at a freshly-green CI) is exactly the human-backpressure you exist to replace.

Two traps the base instinct misses even when it resists "open = done":

1. A green check can flip red. Late-starting jobs and slow stages mean an initial all-green is not a final all-green.
2. The watch ends at merge, not at first green. New commits, reviewer comments, and conflicts arrive after CI goes green.

When to Use

• You (or the main agent) just opened a PR, or CI is running on one, and the goal is to get it merged.
• Asked "is it merged / did it land / is CI done yet?" on a PR you own.
• Tempted to report the task complete because the PR is open or CI just went green.

Not for: opening the PR itself; deciding whether to open one; code review of the diff (that is the reviewer skills). This is purely the watch-until-landed loop.

"Landed clean" — the sufficiency bar

Report done only when all hold; otherwise keep monitoring or name the blocker:

• PR state is MERGED (not just approved, not just green).
• Every required check is green — confirmed, not assumed (statusCheckRollup).
• No unresolved review-bot or human comments.
• No conflict (mergeStateStatus is not DIRTY) and the branch is not stale (BEHIND) — ideally CLEAN.

The monitoring loop

digraph pr_monitor {
    "PR open" [shape=box];
    "Watch checks to completion" [shape=box];
    "All required checks green?" [shape=diamond];
    "Read failing logs, fix root cause, push" [shape=box];
    "Hold a green minute (≥60s continuously green)" [shape=box];
    "Anything flipped red / new check started?" [shape=diamond];
    "Comments or conflicts outstanding?" [shape=diamond];
    "Address them (push fix / resolve / reply)" [shape=box];
    "Merge if authorized" [shape=box];
    "Merged?" [shape=diamond];
    "STOP: name the human blocker" [shape=octagon];
    "Landed clean — report done" [shape=doublecircle];

    "PR open" -> "Watch checks to completion";
    "Watch checks to completion" -> "All required checks green?";
    "All required checks green?" -> "Read failing logs, fix root cause, push" [label="no"];
    "Read failing logs, fix root cause, push" -> "Watch checks to completion";
    "All required checks green?" -> "Hold a green minute (≥60s continuously green)" [label="yes"];
    "Hold a green minute (≥60s continuously green)" -> "Anything flipped red / new check started?";
    "Anything flipped red / new check started?" -> "Watch checks to completion" [label="yes — restart clock"];
    "Anything flipped red / new check started?" -> "Comments or conflicts outstanding?" [label="no"];
    "Comments or conflicts outstanding?" -> "Address them (push fix / resolve / reply)" [label="yes"];
    "Address them (push fix / resolve / reply)" -> "Watch checks to completion";
    "Comments or conflicts outstanding?" -> "Merge if authorized" [label="no"];
    "Merge if authorized" -> "Merged?";
    "Merged?" -> "STOP: name the human blocker" [label="no — needs approval/permission"];
    "Merged?" -> "Landed clean — report done" [label="yes"];
}

gh mechanics (quick reference)

Need	Command
Watch checks (background, 1-min poll, 10-min cap)	timeout 600 gh pr checks <pr> --watch --interval 60 &
Structured status in one shot	gh pr view <pr> --json state,mergeStateStatus,reviewDecision,statusCheckRollup
Read only the failing job's logs	gh run view <run-id> --log-failed
Read review-bot / human comments	gh pr view <pr> --comments
Merge when authorized	gh pr merge <pr> --squash (or repo's strategy)

Key mergeStateStatus values: CLEAN (mergeable), BLOCKED (needs approval/required check), BEHIND (must update branch), DIRTY (conflict), UNSTABLE (a non-required check failing).

Cadence & backgrounding (defaults)

Always monitor in the background — never block the session. The user must be able to keep prompting while the PR is watched, so run the watch as a background job (&, or your harness's background-task / re-invoking monitor) and check back on it. A foreground gh pr checks --watch that holds the terminal is wrong here — it freezes the user out.

• Default window: 10 minutes of active polling per round (timeout 600).
• Default poll interval: 1 minute (--interval 60) — not a tight loop, not once-and-walk-away.
• When the 10-min window elapses without landing: report the current state (which checks are pending/red, review status, mergeability) and kick off another background round. Don't declare done and don't silently drop the watch — the task is still "land it"; the window only bounds each pass so you surface progress and stay responsive.
• Defaults only: a BACKPRESSURE.md may override the window/interval, and an obviously fast/slow pipeline can adjust — but the background, non-blocking rule always holds.

Background ≠ abandoned — the loop is not over until merged.

Handling each outcome

• A check fails: read --log-failed, fix the root cause, push. Do not re-run jobs hoping for a pass — a red check is unresolved work, and a flaky-looking failure on your own change is usually your change. (See [[general-code-review]] if the failure points at a logic/type defect.)
• Late comments arrive: review bots (CodeRabbit, linters) and humans often comment 1–3 min after green. Address real findings; reply to or dismiss noise — don't merge over unresolved blocking comments.
• BEHIND: update the branch from base, which re-triggers CI — back to watching.
• Can't merge (BLOCKED, missing approval, no permission): that is a genuine human blocker. STOP and name it precisely ("CI green and mergeable; branch protection needs one human approval") — do not report success.

Common rationalizations

Rationalization	Reality
"PR is open, task done — I'll log off"	Open ≠ landed. The watch has barely started.
"Local tests passed, CI will be the same"	CI is a different environment; that's the point of CI. Confirm green on CI.
"All 7 checks are green, we're done"	Green ≠ merged, and a 30-second-old green can still flip. Hold the green minute, then merge.
"A check went red, just re-run it"	Re-run-until-green hides a real failure. Read the log, fix the cause.
"Green now, I can stop watching"	Comments and conflicts land after green. Watch until merged.
"I'll report done and mention CI is still running"	A status that depends on an unverified future is a false completion claim.
"I'll just --watch in the foreground until it's done"	That blocks the session so the user can't prompt. Run it in the background, poll every minute (default 10-min window).

Red flags — STOP

• About to report the task complete while the PR is open but not merged.
• About to trust an all-green that has been green for less than a minute.
• About to re-run a failing check instead of reading its log.
• About to stop watching at first green instead of at merge.
• Treating "can't merge, needs approval" as done instead of as a named blocker.
• Blocking the session with a foreground watch instead of monitoring in the background.