monitor-pr

name	monitor-pr
description	Monitor a pull request until CI status or Copilot review is available. Use when: monitor PR, watch PR, land PR, wait for CI, wait for checks, wait for review, check PR status. Starts two async terminal tasks (CI + Copilot review) and reacts when either completes.

Monitor PR

Monitor a pull request by running two scripts in async terminals: one that waits for a Copilot code review, and one that waits for CI to finish. When either terminal exits, the host's async-terminal runtime notifies the agent on its next turn, so the agent can react without polling.

Host requirement: this skill assumes the agent host can run long-lived background terminals and notify the agent when they exit — for example, VS Code Chat's run_in_terminal with mode=async plus get_terminal_output / kill_terminal. Hosts without that capability will need to adapt the procedure (e.g. foreground the scripts and block on them).

When to Use

• After creating a PR and you want to wait for CI and Copilot's review
• When the user says "land this PR", "watch this PR", "monitor CI", or "wait for checks"

Prerequisites

• gh CLI installed and authenticated.
• An active PR — created earlier in the conversation, or supplied by the user as a number or URL.

Procedure

1. Identify the PR

Extract the PR number from the conversation context. Determine the repo with:

gh repo view --json nameWithOwner -q .nameWithOwner

2. Start Two Async Terminals

Run BOTH of these scripts in separate async terminals (mode=async on run_in_terminal, or your host's equivalent). Use a small timeout, such as timeout=1000, so the tool returns quickly after the monitor process starts. Do NOT await them and do NOT poll or sleep; the runtime will notify you on a later turn when each script exits.

The scripts live inside this skill directory, at <skill-dir>/scripts/wait-for-ci.mts and <skill-dir>/scripts/wait-for-copilot-review.mts. Always invoke them by absolute path — derive the skill directory from the absolute path of this SKILL.md, not from the current working directory. The agent's CWD is usually the user's project repo, not this plugin.

Terminal A — wait for Copilot code review:

node <skill-dir>/scripts/wait-for-copilot-review.mts <pr-number> <owner/repo>

Terminal B — wait for CI:

node <skill-dir>/scripts/wait-for-ci.mts <pr-number> <owner/repo>

After launching both, record their terminal IDs and stop. Return control to the user with a brief status message, for example: "Monitoring PR #N — waiting for CI and Copilot review."

3. React to Notifications

When you are notified that one of these terminals has exited, read its output with get_terminal_output and act on the RESULT: line. The terminal output already contains everything you need — read it carefully before taking any action.

Script	Result	Exit	Action
wait-for-copilot-review.mts	UNRESOLVED_COPILOT_REVIEW_COMMENTS	0	Unresolved Copilot comments existed before monitoring started. The output lists each comment (file, line, body). Follow step 4 below.
wait-for-copilot-review.mts	NEW_COPILOT_REVIEW	0	A new Copilot review arrived after monitoring started. The output lists each new inline comment (file, line, body). Follow step 4 below.
wait-for-copilot-review.mts	NO_COPILOT_REVIEW_EXPECTED	0	No applicable automatic-review rule or explicit request exists, so the script exited without waiting. Report the status and move on.
wait-for-copilot-review.mts	COPILOT_REVIEW_TIMEOUT	0	No new Copilot review or unresolved Copilot comments appeared during the 15-minute monitoring window. Report the status and move on — do not try to request a review yourself.
wait-for-copilot-review.mts	COPILOT_REVIEW_ERROR	2	Report the script or gh error output to the user.
wait-for-ci.mts	CI_PASSED	0	CI is green. Report the status and keep waiting for the review terminal if it is still running.
wait-for-ci.mts	CI_PASSED_POLICY_PENDING	0	Actual CI is green, but non-build review-policy checks are not passing yet. Report both facts and keep waiting for the review terminal if it is still running.
wait-for-ci.mts	MERGE_CONFLICT	1	The PR is conflicting/dirty. Resolve the merge conflict, push the resolution, and restart both monitors.
wait-for-ci.mts	CI_FAILED	1	Follow step 5 below.
wait-for-ci.mts	CI_ERROR	2	Report the script or error output to the user.

If only one of the two terminals has completed, leave the other running.

4. Addressing Copilot Review Comments

After a NEW_COPILOT_REVIEW or UNRESOLVED_COPILOT_REVIEW_COMMENTS result:

1. Repeat the Copilot review comments to the user before making edits. Include the file, line, and body from the terminal output so the user can see exactly what Copilot asked for.
2. Handle each comment immediately using your own judgment. This may mean editing code, deciding the comment is not worth changing, or confirming that no code change is needed.
3. Resolve the corresponding Copilot review thread as soon as you have handled it. Resolve it even when you decide not to make a code change. Do not leave Copilot comment threads open after they have been considered. Tell the user that you've resolved the comments.

Use the following commands to find and resolve Copilot review threads after handling each comment.

To find unresolved Copilot thread IDs:

gh api graphql -f query='{ repository(owner: "<owner>", name: "<repo>") { pullRequest(number: <N>) { reviewThreads(first: 50) { nodes { id isResolved comments(first: 1) { nodes { body author { login } } } } } } } }' -q '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | select(.comments.nodes[0].author.login | test("copilot"; "i")) | {id, body: (.comments.nodes[0].body[:80])}'

To resolve a thread:

gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "<THREAD_ID>"}) { thread { isResolved } } }'

Resolve only the Copilot threads you have handled. If multiple Copilot comments map to the same underlying issue and a single edit handles all of them, resolve all of those handled threads before stopping.

5. Handling CI Failures

When wait-for-ci.mts reports CI_FAILED, investigate whether the failures are real or flaky before doing anything else.

1. Identify the failing jobs with gh pr checks <pr-number> and look up the run ID from the failed job URL.
2. Read the failed logs with gh run view --job <job-id> --log-failed and search for the actual error (test name, assertion, build error, etc.). Skip past cleanup/teardown output to the real failure line.
3. Decide whether the failure is flaky. Treat a failure as flaky only if ALL of the following hold:
   • The PR's actual file changes have no plausible connection to what failed (for example, a docs-only PR failing an integration test in an unrelated area).
   • The failure looks timing-sensitive, environment-related, or matches a known infrastructural pattern for this repo's CI (network timeout, missing artifact, ECONNRESET, runner disconnected, lock contention, etc.) rather than a clean assertion in code the PR touched.
   • The failing test is known to be flaky in the repo (referenced in an existing issue, tagged as flaky, or the failure mode is obviously infrastructural such as npm install failing or a download retry being exhausted).
4. If the failure looks flaky, retry just the failed jobs without asking the user:

   gh run rerun <run-id> --failed
   

   Then kill the old wait-for-ci.mts terminal with kill_terminal and start a fresh one per step 2. Tell the user briefly that you identified the failure as an unrelated flake and retried it.
5. If the failure looks real (touches code you changed, clean assertion failure, compile error in your diff, etc.), do NOT retry. Explain the failure to the user and fix it. If you are not confident you understand the failure, ask the user for guidance instead of guessing at a fix.
6. Never retry the same job more than once in this conversation without the user's explicit permission. If a retried job fails again, stop and treat it as a real failure even if it still looks flaky.

6. After Pushes

New commits re-trigger CI and may invalidate the existing Copilot review. After pushing fixes, kill any still-running monitor terminals with kill_terminal and re-run this skill to watch the fresh run.

Notes

• Both scripts poll every 30 seconds to avoid hitting API rate limits, so there is up to ~30s of latency between an event occurring on GitHub and the script reporting it. Each poll also prints a progress line to stdout so the agent can confirm the monitor is still alive when reading the terminal output.
• wait-for-ci.mts checks mergeability before checks and reports MERGE_CONFLICT immediately for conflicting/dirty PRs.
• wait-for-ci.mts ignores the non-build VS Code PR Check and Community PR Approvals policy checks when deciding whether actual CI is complete. Draft PRs therefore report CI_PASSED_POLICY_PENDING once their actual build checks finish.
• wait-for-ci.mts exits immediately on the first poll that contains any failed or cancelled check; it does not wait for other checks to finish. All currently-failed checks at that moment are listed in the output.
• wait-for-copilot-review.mts expects an initial review for microsoft/vscode* repositories. Elsewhere it waits when an applicable branch rule has type: copilot_code_review or Copilot is visibly requested. It honors the rule's draft and new-push settings and does not wait when the current head was already reviewed. Otherwise it reports NO_COPILOT_REVIEW_EXPECTED immediately. GitHub does not expose personal automatic-review settings, so those cannot be detected.
• Once a review is expected, an empty requested_reviewers list does not end the wait because automatic reviews may never appear there. The script checks unresolved Copilot threads and new review IDs every 30 seconds for up to 15 minutes.