github-workflow-watch-pr

name	github-workflow: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 guide for monitoring GitHub PRs. Read this BEFORE starting any PR monitoring to avoid silent failures.

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

Evaluation Priority

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

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 code-review: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 code-review: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.
• code-review:check-pr — CI failure log analysis and review comment fix workflows.
• code-review: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