watch-pr

name	watch-pr
description	This skill should be used when the user asks to 'watch PRs', 'monitor PR status', 'PRを監視', 'PRの状態を見て', 'babysit this PR', 'PRが通るまで見て', or when the agent needs to monitor PR health after push, PR creation, or CI failure detection.
tools	["Read"]

Watch PR

Reference and workflow guide for monitoring GitHub PRs. Covers both the monitoring procedure and edge cases that silently break monitoring.

Read references/pitfalls.md for the full list of edge cases that silently break PR monitoring.

Monitoring Workflow

function monitor_pr():
  pr = resolve_target_pr()
  report_to_user("monitoring started", pr.url)

  loop:
    state = query_pr_state(pr)

    if state.state in [MERGED, CLOSED]:
      report_to_user("PR is " + state.state + " — monitoring complete")
      return

    if state.autoMergeRequest is not null:
      // Do NOT attempt merge — auto-merge handles it
      // Only fix blockers (CI failures, conflicts, review requests)

    action = evaluate_priority(state)  // See "Evaluation Priority" below

    if action was already executed in the previous iteration and no new state change occurred:
      // Avoid re-fixing the same issue (e.g., review comments already addressed, awaiting re-review)
      report_to_user("awaiting external action: " + action.waiting_for)
      wait_for(external_state_change)  // e.g., reviewer re-reviews, CI re-runs
      continue

    execute(action)
    report_to_user(action.summary)

    if action.requires_wait:
      // e.g., CI pending → spawn ci-watcher, then re-enter loop on completion
      wait_for(action.completion_signal)

    // Re-check from top: conflicts may appear during CI, base may update
    continue

function resolve_target_pr():
  // Option 1: PR number given by user → use directly
  // Option 2: Current branch → gh pr view --json number,url
  // Option 3: Multiple PRs for branch → ask user to select
  branch = current git branch
  return gh pr view {branch} --json number,url,headRefName

function query_pr_state(pr):
  // Called on EVERY loop iteration (including after push). Null-retry applies each time.
  state = gh pr view {pr.number} --json mergeable,mergeStateStatus,isDraft,state,autoMergeRequest,reviewDecision
  if state.mergeable is null:
    retry 2-3 times with 2s delay
    if still null: report "merge state not yet computed" and defer

  // CI status is NOT in mergeStateStatus — query separately, but only after confirming no conflicts
  if state.mergeStateStatus != "dirty":
    state.ci = gh pr checks {pr.number}
    // ci has per-check status: pass / fail / pending / no-ci
  return state

Report to the user at each state transition — not just at the end. When spawning ci-watcher for background monitoring, report immediately that CI is being watched, then report again when CI completes.

Evaluation Priority

When monitoring a PR, evaluate conditions in this order. The first match determines the action — do NOT skip ahead.

How to determine each condition:

• Conditions 1–2: from mergeStateStatus (in query_pr_state). If mergeStateStatus is unknown, treat as non-dirty/non-behind and proceed to CI check — GitHub has not yet computed the state.
• Conditions 3–5: from gh pr checks output (in query_pr_state.ci). CI failed = any required check has conclusion failure/timed_out/startup_failure. CI pending = any check has status in_progress/queued and none have failed.
• Condition 6: from isDraft
• Conditions 7–9: from reviewDecision and individual review states
• Conditions 11–13: combine reviewDecision with mergeStateStatus — clean → ready to merge, blocked → check branch protection

1. Merge conflicts (mergeStateStatus: dirty) — Resolve conflicts FIRST. GHA pull_request workflows are not dispatched while conflicts exist (see "Key Rule" below).
2. Branch behind base (mergeStateStatus: behind) — If "require branches to be up to date" is enabled, run git fetch origin && git merge origin/<base> && git push to update the PR branch.
3. CI failed (draft PR) — Fix CI failures even on drafts. CI issues should be resolved before the PR is marked ready for review. Draft status is reported separately at step 6.
4. CI failed (non-draft) — Fix CI failures via check-pr CI checker.
5. CI pending — Wait. Spawn ci-watcher agent in background.
6. PR is draft — Report draft status. User decides next step.
7. Changes requested — Fix review comments via check-pr review checker.
8. Approvals dismissed by push — Report. Reviewers need to re-approve.
9. Reviews required, not yet submitted (blocked) — Waiting on reviewers. Report pending.
10. Approved but blocked — Merge queue or other branch protection. Wait.
11. Approved, clean — Ready to merge (or auto-merge handles it).
12. No reviews required/submitted, clean — Ready to merge.
13. No reviews required/submitted, blocked — Check branch protection settings.
14. No CI configured — Proceed to review/merge checks.

Key Rule: Conflicts Before CI

Per GitHub's official documentation: "Workflows will not run on pull_request activity if the pull request has a merge conflict. The merge conflict must be resolved first." This is confirmed by real-world observation across multiple projects — GHA workflows are not dispatched and do not appear in gh pr checks.

Exceptions:

• pull_request_target trigger — Runs even with conflicts (it targets the base branch, not the merge ref).
• External integrations (Vercel, CodeRabbit, etc.) — May still run on the head commit and report results.
• push-triggered workflows — Run on the head commit regardless, but do not test the merged state.

Always check conflict status first. If conflicts exist, resolve them before evaluating CI — GHA checks will not arrive until the PR is conflict-free.

Always run gh pr view --json mergeable,mergeStateStatus BEFORE gh pr checks.

Re-check Conflicts After CI

The base branch may be updated by other merges while CI is running. After CI completes, re-check the PR merge state — conflicts may have appeared during the CI run, invalidating the results.

mergeStateStatus Values

Possible values for the REST API mergeable_state field (lowercase) and the GraphQL MergeStateStatus enum (uppercase). Not all values are documented — some are observed in practice.

• clean — Mergeable and passing commit status. Review status is NOT encoded here — check reviewDecision (GraphQL only) separately.
• dirty — Merge conflicts exist. GHA pull_request workflows will not run.
• blocked — Branch protection rules not met (required reviews, required checks pending or failed, or merge queue).
• unstable — Mergeable with non-passing commit status. The failing checks are non-required — if required checks fail, the state is blocked instead.
• behind — Head branch is behind the base branch. May need to update before merging if "require branches to be up to date" is enabled.
• unknown — GitHub has not yet computed the merge state.
• has_hooks / HAS_HOOKS — Observed (not officially documented): mergeable with passing commit status and pre-receive hooks present. Primarily seen on GitHub Enterprise Server. Treat as a positive state similar to clean.

mergeable Can Be null

GitHub computes mergeability asynchronously. The first API call after a push often returns mergeable: null. Retry 2-3 times with 2-second delays. Do NOT proceed with monitoring until mergeable has a definitive value.

Delegating to Existing Tools

• ci-watcher agent — Background CI watching after confirming no conflicts. Auto-detects current branch PR.
• check-pr — Covers three workflows; invoke by framing context:
  • Conflict/behind check: invoke first. Detects mergeStateStatus DIRTY/BEHIND and resolves before proceeding.
  • CI failure fix: invoke after identifying failed checks. The skill reads CI logs and applies fixes.
  • Review comment fix: invoke after CI is green and reviewDecision is CHANGES_REQUESTED. The skill reads review comments and addresses them.
• github-pr — Lower-level utility scripts. Use via check-pr, not directly.

References

• references/pitfalls.md — GitHub PR monitoring pitfalls — edge cases that silently break monitoring workflows