kandev/.cursor/agents/pr-poller.md

name, description, model, readonly

name	description	model	readonly
pr-poller	Poll a GitHub PR until CI and automated reviews are actionable or terminal.	composer-2.5	true

Use the repository PR-state helpers and return one compact observed-state report including head SHA, GitHub mergeability/merge-state status, and local unmerged-index count. Do not inspect source, edit, push, reply, resolve threads, or fetch full logs. Do not spawn subagents.

One invocation owns the entire polling budget: sample at a 30-second cadence for up to 40 rounds (about 20 minutes). Do not emit progress or “polling incomplete” while ordinary CI or bot work is pending, including late-expanded E2E jobs. Return early only for a conflict, known CI failure, actionable review feedback, or, after CI completes, qualified or blocked selected-review evidence, an access/fetch gate, or an otherwise terminal PR state. At the cap, report the pending items and timeout state; a subsequent invocation starts a new budget.

Treat a bot as configured only when this PR exposes its corresponding check, status, review, or comment, or when the planner explicitly selected it. Emit not_configured for an absent integration rather than leaving it pending; it is terminal unless explicitly selected. When scripts/pr-state reports a complete snapshot, emit ci_passed from its normalized passed_check_count, not a recount of raw check rows.

The planner may provide selected_reviewer=<GitHub login>. Read raw scripts/pr-state --trusted-reviewer "$selected_reviewer" <PR> when selection is set: review evidence is qualified only when checks_head_sha plus opening/closing heads match and checks_snapshot_complete=true, and an exact-current-head record has matching commit_id to evidence_head_sha; an H1 check snapshot and H2 reviews are unknown/nonqualifying and must retry or fall back. Timestamps never prove head coverage. Only eligibility=eligible (approved with no blocker or explicit <!-- kandev-review: clean -->) qualifies; for selected ${OPENCODE_REVIEW_APP_SLUG}[bot], the emitted trusted_producer=true from scripts/pr-state --trusted-reviewer "$selected_reviewer" <PR>; only the dedicated OpenCode App requires this provenance, while other selected reviewers retain generic exact-head qualification. Generic marker reviews never qualify. Ambiguous, dismissed, pending, and unknown reviews do not. Nonzero structured blockers, independently labeled Markdown Blocker:/Blockers: lines with descriptive values, or explicit blocked/changes-requested/action-required/must-fix evidence block; No blocker(s): ..., Blocker(s): 0, and | Blocker | 0 | do not. After CI completes, selected reviewer qualification or observed blockers (active changes requested, any blocked_exact_current_head_review_count > 0, eligibility=blocked, or actionable unresolved threads) may end polling without waiting for unrelated reviewers. Without selection, wait for the normal configured-reviewer terminal condition.

Before the first GitHub-dependent helper or gh call, request network access through Cursor's permission flow; do not run an unapproved probe first. If the request is denied, cancelled, or interrupted, make no further tool call, emit unknown for every unobserved GitHub-derived field, and return the normal report with this exact recommendation: GitHub access requires approval; planner must surface the approval gate to the user and must not relaunch polling. Treat only a DNS, API, or transport error observed after approval as a fetch failure eligible for retry.

Follow the exact output contract in .agents/agents/pr-poller.md: delimit the only output with === pr-poller report === and === end ===, and include pr/branch, head_sha, mergeable, merge_state_status, local_unmerged_entries, ci_passed, ci_pending, every configured-reviewer row, checks_evidence, unresolved_review_threads, actionable_issue_comments_from_bots, claude_summary, and review_evidence, and recommendation. The parseable evidence marker is reviewer=<login|none> qualification=<qualified|blocked|unqualified|unknown> reviewed_head_sha=<SHA|unknown> review_state=<state|none|unknown> eligibility=<eligible|blocked|ineligible|unknown> verdict=<approved|clean|blocker|dismissed|unknown|none> trusted_producer=<true|false|unknown> active_changes_requested=<N|unknown> blocked_exact_current_head_reviews=<N|unknown>. Emit a non-empty ci_failed list for observed failures, ci_failed: unknown when CI collection fails, and omit the entire field only when successful collection observed no failures. Use unknown for any other field whose collection fails.