PR Monitoring Loop

Run a reusable PR monitoring loop while keeping the main agent's context small.

Input: A PR number or URL, plus any workflow-specific readiness criteria such as required labels, required approving bot, or timeout rules.

The state file is optional. If you do not pass --state-file, the script auto-creates one at .agents/skills/pr-monitoring-loop/scripts/state/.pr-monitor-<pr>.json (gitignored) on first run and reuses it on every subsequent call for the same PR. You can call the script directly with just a PR number and "new vs old" detection still works across invocations. Override --state-file <path> only when you need an isolated state file (for example, parallel watchers on different branches but the same PR number, or tests). Pass --no-state to disable persistence entirely (every comment will be reported as new every poll).

verify-openspec behavior is opt-in. Do not add the verify-openspec label, wait for a verify approval review, or apply any OpenSpec-specific completion rule unless the caller explicitly asks for that behavior.

High-Level Flow

1. The main agent starts one delegate subagent for the PR. The delegate simply invokes the script; the script auto-creates and reuses .agents/skills/pr-monitoring-loop/scripts/state/.pr-monitor-<pr>.json (gitignored) by default. Pass --state-file <path> only if you need isolation. Do NOT put state under .git/ — this repo uses git worktrees, where .git is a file pointing at a worktree-specific git dir, which would fragment state across worktrees watching the same PR.
2. The delegate polls the PR with scripts/check-pr-state.py --state-file <path>. The state file persists "seen" IDs and lastPolledAt so a fresh subagent can still tell new feedback from old.
3. The delegate continues until something is actionable:
   • CI check failure (commit-pinned)
   • new PR review comment, new conversation comment, or new unresolved review thread (judged by summary.new* fields, not totals)
   • blocking review state — summary.reviews.effectiveDecision == "CHANGES_REQUESTED" (a later APPROVED supersedes an earlier CHANGES_REQUESTED)
   • merge conflict or out-of-date branch
4. If the delegate judges the resolution simple, it may implement the fix, commit it, push it, perform the thread-resolution protocol below for any addressed threads, and continue watching.
5. If the delegate judges the resolution non-simple, ambiguous, risky, or needing product judgment, it reports the actionable item to the main agent.
6. The main agent launches a fresh delegate subagent scoped only to that fix, passing the same --state-file path so seen IDs persist.
7. After the delegate commits, pushes, replies, and resolves addressed threads, the main agent starts a fresh watch cycle for the new PR head.
8. Repeat until the PR reaches the caller's success criteria or the loop is blocked.

Main Agent Instructions

When entering PR monitoring:

1. Create the PR first if needed and record its PR number or URL.
2. State persistence works out of the box — the script auto-uses .agents/skills/pr-monitoring-loop/scripts/state/.pr-monitor-<pr>.json, so a fresh subagent invoking the script with only a PR number still sees previously seen IDs. Pass --state-file <path> explicitly to every subagent only when you need an isolated state file (e.g., parallel watchers, tests). Do NOT put state under .git/ — see the worktree note above.
3. Launch a write-capable delegate subagent with this skill's watcher prompt.
4. Do not poll GitHub directly in the main agent except to recover from a delegate failure.
5. If the delegate returns an actionable item for delegation:
   • launch a fresh write-capable delegate subagent
   • scope it only to the reported CI failure, review feedback, comment, conflict, or branch freshness issue
   • require minimal commits, a push to the PR branch, and the thread-resolution protocol for any addressed threads
   • restart the watch after the delegate finishes, again passing the same --state-file
6. Stop and ask the user when the watcher or delegate reports that the next decision needs user input.

Watcher Prompt

Tell the watcher subagent:

Monitor PR <pr> using:

  .agents/skills/pr-monitoring-loop/scripts/check-pr-state.py <pr>

(The script auto-creates and reuses a state file at
`.agents/skills/pr-monitoring-loop/scripts/state/.pr-monitor-<pr>.json` so "new since last poll"
detection survives across fresh subagents. Only pass `--state-file <path>` if the main agent
explicitly asked you to use a non-default state file.)

Drive every decision off the script's focused output. In particular:
- New work appears as `comments.newIssueComments`, `comments.newReviewComments`,
  `threads.unresolvedNew`, `threads.unresolvedUpdatedSinceHead`, and
  `reviews.newReviewIds`. Old totals stay under `comments.totalIssueComments` / `comments.totalReviewComments` for reference but MUST NOT
  drive the actionable decision.
- Review state is `reviews.effectiveDecision` (latest review per reviewer; a later APPROVED
  supersedes an earlier CHANGES_REQUESTED).
- verify-openspec state is `verifyOpenspec.requiresOpenspecVerification`. When `true`, apply the `verify-openspec` label. When `false`, do not touch the label.
- CI is `checks` (which prefers commit-pinned data over `gh pr checks` rollup).

Poll until one of these happens:
- the PR satisfies the provided success criteria
- a CI check fails (`failed_checks` in `summary.actionable`)
- there is a new actionable PR comment, review comment, unresolved review thread, or
  CHANGES_REQUESTED review (any of `issue_comments`, `review_comments`, `unresolved_review_threads`,
  `changes_requested` in `summary.actionable`)
- the PR has a merge conflict or stale branch state
- the loop is blocked or has timed out

You may fix and push changes yourself when you judge the fix simple, including mechanical lint,
formatting, generated artifacts, obvious test expectation updates, small typo fixes, or other
low-context changes. After pushing, perform the thread-resolution protocol (see "Thread
resolution" below) for every thread your fix addresses, then continue watching the new PR head.

Return work to the main agent when the fix is non-simple, ambiguous, risky, spans multiple
concerns, requires product/API judgment, repeats after an attempted fix, or needs user input.

Print the entire script output JSON before deciding. In your final result include:
- status: `ready`, `fixed-and-continued`, `delegate`, `blocked`, or `timeout`
- PR URL and head SHA
- actionable item summary
- evidence from `check-pr-state.py` (paste the relevant excerpt, e.g. `actionable`, `checks.failedChecks`, `threadDetails`)
- counts of seen vs new IDs you observed
- fixes you committed and pushed, threads you replied to and resolved (with thread ids)
- recommended delegate scope when status is `delegate`

Cadence enforcement

Prefer --watch over hand-rolled sleep loops:

• Active CI window (checks pending, fast iteration): --watch --interval 60.
• Acceptance-test-only window (only long-running jobs left): --watch --interval 300.
• Always set --max-duration so the subagent can't run unbounded; size it to the expected window.

--watch exits with code 0 on the first actionable tick (and prints a {"final": true, "outcome": "actionable", ...} line), 124 on timeout, and 2 on a transient gh failure that survived retries. Each tick is one NDJSON line; the watcher should stream and react to those.

After every push, restart the watch cycle for the new PR head SHA. The state file is updated automatically each tick.

Deterministic PR state

Use:

.agents/skills/pr-monitoring-loop/scripts/check-pr-state.py <pr>

The script auto-creates a state file at the default path on first run; pass --state-file <path> only when you need an isolated state file, or --no-state to disable persistence entirely.

When invoked without --full-payload (the default) the script returns a focused JSON payload containing only actionable decision data. The raw data arrays (prChecks, commitCheckRuns, commitStatuses, reviews, issue_comments, review_comments, review_threads, issue_events, merge_conflicts) are not included in the default output; use --full-payload when you need them.

The focused output contains:

• pr: number, url, title, headRefName, headRefOid, mergeable, mergeStateStatus, labels
• checks: source, headSha, total, failed, pending, passed, failedChecks[] with {name, url}, pendingNames
• comments: totalIssueComments, totalReviewComments, newIssueCommentIds, newReviewCommentIds, newIssueComments[] with {id, author, body}, newReviewComments[] with {id, author, body}
• threads: unresolved, unresolvedNew, unresolvedUpdatedSinceHead, unresolvedThreadIds, unresolvedNewThreadIds
• threadDetails: keyed by thread id, includes path, line, resolved, outdated, comments[] with {author, body, databaseId}
• reviews: total, newReviewIds, effectiveDecision, latestByReviewer, newReviews[] with {author, state, id}
• verifyOpenspec: runState, requiresOpenspecVerification
• merge: blocked, hasConflicts, conflictFiles, conflictAnalysisAvailable, mergeable, mergeStateStatus
• actionable: list of string signals
• hasActionable: bool
• headPushedRecently: bool

Top-level fields the watcher consumes (there is no separate summary dict; the root object is the summary):

• actionable (list of strings) and hasActionable (bool)
• checks.{source, total, failed, pending, passed, failedChecks[], pendingNames} — failedChecks[] has {name, url} for log lookup; source is commit-pinned when canonical, pr-checks when falling back
• comments.{totalIssueComments, totalReviewComments, newIssueComments, newReviewComments, newIssueCommentIds, newReviewCommentIds} — newIssueComments[] and newReviewComments[] include {id, author, body} when there is new content
• threads.{unresolved, unresolvedNew, unresolvedUpdatedSinceHead, unresolvedThreadIds, unresolvedNewThreadIds}
• threadDetails.{<threadId>}.comments[].databaseId — the REST id needed for in_reply_to in the thread-resolution protocol
• reviews.{total, newReviewIds, latestByReviewer, effectiveDecision, verifyOpenspec}
• verifyOpenspec.{runState, requiresOpenspecVerification} — use requiresOpenspecVerification as the single trigger for applying the label
• merge.{blocked, hasConflicts, conflictFiles, ...}
• headPushedRecently is true when the head SHA changed since the last poll recorded in the state file

Run the test suite with:

python -m pytest .agents/skills/pr-monitoring-loop/scripts/tests