Copilot PR Autopilot

Drive any GitHub pull request through repeated rounds of Copilot code review until the agent has done its job — every Copilot finding has a reply from the agent (fix-acknowledgement, decline-with-rationale, or explicit escalate-to-user hand-off). Remaining open threads, if any, are deliberate hand-offs to the human merge owner — they're not loop failures. Repository-agnostic — works on any repo that has Copilot Code Review enabled, run from a machine with gh CLI installed and authenticated (see Prerequisites).

When to Use This Skill

• The user asks to "request Copilot review" or "run a Copilot review loop"

on a PR.

• A PR is functionally complete and the user wants a final correctness pass

via repeated automated review rounds.

• A previous Copilot review on the PR has left open threads that need

triage, fixing, replying, and resolving.

When NOT to Use This Skill

• The PR is still under active design — wait until the structure is stable;

otherwise findings churn round-over-round.

• The user wants human reviewer feedback, not Copilot's.

Prerequisites

• gh CLI installed and authenticated against the target repository.
• PowerShell on PATH — Windows PowerShell 5.1+ (powershell.exe) or

PowerShell 7+ (pwsh). Both are tested.

• Copilot Code Review is the primary use case (01-request-review.ps1

uses GraphQL requestReviewsByLogin to trigger Copilot). It is NOT a hard requirement — if 01-request-review.ps1 fails because Copilot isn't enabled on the repo / account, the agent can still drive existing review threads (human, advanced-security, etc.) to completion by running steps 3–8 once as a single iteration; just skip the trigger + wait. There is no auto-detect for "Copilot unavailable" — the agent makes that decision after the trigger fails (the script can't reliably tell "Copilot disabled" from "Copilot enabled but not yet triggered" from API state alone).

Permissions: who can run the full loop

The full multi-round autopilot (steps 1 → 9 → 1) needs Triage or Write permission on the target repo, because GitHub's only public API for adding the Copilot bot as a reviewer (requestReviewsByLogin) is gated on that permission. Verified against the public REST + GraphQL surface in this PR's commit history — there is no public-API path for bot reviewers without write permission.

In single-iteration mode the loop's convergence boolean is Converged: true iff OpenThreadsAwaitingReply == 0 (the agent's side is done). The maintainer-side re-trigger then drives any additional rounds.

Every script dot-sources [scripts/lib.ps1](scripts/lib.ps1) which runs Assert-GhReady on load: if gh is missing OR gh auth status fails, the script halts before any work with a single actionable error message naming the install command and gh auth login. The agent should surface that message to the user verbatim and stop the loop — do not retry or work around it.

Step-by-Step Workflow

The loop: steps 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9, then back to step 1 if Converged: false. Repeat the 1→9 round until step 9 returns Converged: true; only then run step 10 once and call task_complete. At every 10th round, the parent runs the [round-cap recap gate](references/09-convergence.md#round-cap--recap-gate-circuit-breaker) before looping back — recap all prior rounds and stop if the loop has drifted out of the PR's original scope.

Each round runs steps 1–9; step 10 is a one-time cleanup after convergence. The parent agent coordinates; every sub-agent step runs in a fresh context with a bounded budget. Cross-cutting protocol (time-boxing, extension, single-iteration fallback): [orchestration.md](references/orchestration.md).

1. Request review (parent) — see [01-request-review.md](references/01-request-review.md)
2. Wait for review (sub-agent, 20-min cap) — see [02-wait.md](references/02-wait.md)
3. List + categorize open threads (sub-agent, 5 min) — see [03-list-threads.md](references/03-list-threads.md)
4. Triage (sub-agent, 5 min per ≤5 threads) — see [04-triage.md](references/04-triage.md)
5. Fix (sub-agents, parallel max 5, 5 min each) — see [05-fix.md](references/05-fix.md)
6. Build + test per repo conventions (sub-agent, 10 min) — see [06-build-test.md](references/06-build-test.md)
7. Commit + push (parent) — see [07-commit-push.md](references/07-commit-push.md)
8. Reply (always) + resolve (conditional) (sub-agent drafts, parent posts) — see [08-reply-resolve.md](references/08-reply-resolve.md)
9. Convergence verify (sub-agent, 3 min) — see [09-convergence.md](references/09-convergence.md)

- Converged: false → loop back to step 1 for another round (re-trigger, wait, list, triage, fix, push, reply, re-check). Each round addresses Copilot's findings on the previous round's HEAD; the loop terminates as soon as Copilot has nothing new to say AND every open thread has a reply from the agent. - Converged: true → exit the loop, run step 10 once, call task_complete with the proof. - Every 10th round (10, 20, 30…) → run the [round-cap recap gate](references/09-convergence.md#round-cap--recap-gate-circuit-breaker) before looping back. Recap ALL prior rounds against the PR's original scope and pick a verdict: CONTINUE, REVERT-AND-SHIP (drop drifted commits, ship the in-scope ones), or HAND-OFF (escalate to the user). This is the circuit breaker that stops a runaway bot-review loop.

1. Cleanup outdated (parent, post-convergence, once) — see [10-cleanup.md](references/10-cleanup.md)

Convergence is computed by [scripts/02-check-review-status.ps1](scripts/02-check-review-status.ps1) as a single Converged: true boolean. Do not call task_complete until it returns true; print the proof (HeadOid, LatestCopilotReview.commitOid, submittedAt) in the completion message.

Gotchas

The bundled scripts enforce the hard correctness invariants (trigger landing via copilotworkstarted event id, Converged requiring HEAD-match + zero-awaiting + at-HEAD review, single-iteration fallback semantics, PR-state guard). Trust them — don't re-derive. The notes below cover decisions the scripts can't make for you:

• Reply to every open thread; resolve only when the loop owns the disposition. For fix and decline threads, reply + resolve. For escalate-to-user threads, reply with the analysis but leave the thread OPEN (08-reply-and-resolve.ps1 -NoResolve) so the human merge owner can act on it. See [08-reply-resolve.md](references/08-reply-resolve.md).
• Copilot threads are loop-owned; human / advanced-security / other-bot threads default to escalate-to-user. Auto-resolving a human review thread can hide unaddressed concerns. See [04-triage.md](references/04-triage.md) for the rubric.
• One focused commit per round, not one per PR. Bundling rounds destroys the audit trail of which finding drove which change and breaks git bisect. See [07-commit-push.md](references/07-commit-push.md).
• Build/test/lint with the repo's own commands (per its CONTRIBUTING / AGENTS / README / package.json / Makefile) before pushing a fix. Discovery procedure: [06-build-test.md](references/06-build-test.md).
• Push back with written rationale when a Copilot finding would over-engineer the design for a hypothetical edge case. Auto-accepting every suggestion erodes the design — see the decline path in [04-triage.md](references/04-triage.md).
• Scripting traps (gh api graphql -F type-coercion, git stash push -m positional parsing, the three GraphQL traps for the reviewer mutation) are documented in [references/api-quirks.md](references/api-quirks.md). Read before modifying any script.

Troubleshooting

References

• [references/orchestration.md](references/orchestration.md) —

cross-cutting loop control: time-boxing & extension protocol, sub-agent delegation map, single-iteration fallback, and loop-wide notes.

• Per-step contracts (one NN-*.md per step):

[references/01-request-review.md](references/01-request-review.md) (parent), [references/02-wait.md](references/02-wait.md), [references/03-list-threads.md](references/03-list-threads.md), [references/04-triage.md](references/04-triage.md) (includes the fix-vs-decline rubric), [references/05-fix.md](references/05-fix.md), [references/06-build-test.md](references/06-build-test.md), [references/07-commit-push.md](references/07-commit-push.md) (parent), [references/08-reply-resolve.md](references/08-reply-resolve.md), [references/09-convergence.md](references/09-convergence.md) (includes the round-cap recap gate), [references/10-cleanup.md](references/10-cleanup.md) (parent).

• [references/api-quirks.md](references/api-quirks.md) — verified

GitHub API behavior, dead-ends, and the GraphQL traps for the reviewer mutation.

• Templates (one per reply type):

[templates/reply-fix.md](templates/reply-fix.md) — accepted-fix pattern; [templates/reply-decline.md](templates/reply-decline.md) — declined-with-rationale pattern; [templates/reply-drift.md](templates/reply-drift.md) — PR-description / comment / test-plan drift acknowledgement; [templates/reply-partial.md](templates/reply-partial.md) — partial fix with deferred follow-up. Cross-cutting reply guidance and anti-patterns live in [references/08-reply-resolve.md](references/08-reply-resolve.md#reply-guidance).

• [scripts/lib.ps1](scripts/lib.ps1) — shared helpers (Invoke-Gh,

Invoke-GhGraphQL, Resolve-RepoCoords); dot-sourced by every script.

• [scripts/01-request-review.ps1](scripts/01-request-review.ps1) —

trigger Copilot review and verify pickup via the copilotworkstarted event.

• [scripts/02-check-review-status.ps1](scripts/02-check-review-status.ps1) —

single-shot snapshot of the PR's Copilot review state; emits Converged: true only when all three conditions hold.

• [scripts/03-list-open-threads.ps1](scripts/03-list-open-threads.ps1) —

every unresolved PR review thread from all reviewers (Copilot, humans, github-advanced-security, etc.).

• [scripts/08-reply-and-resolve.ps1](scripts/08-reply-and-resolve.ps1) —

post a reply and resolve in one call.

• [scripts/10-cleanup-outdated.ps1](scripts/10-cleanup-outdated.ps1) —

safety net for outdated Copilot threads.