copilotloop · diff
v1.1 to v1.2
85 added, 89 removed. Audit A to A.
---
name: copilotloop
description: >
Iteratively satisfy GitHub Copilot's code review on a GitHub PR, but treat every Copilot comment
SKEPTICALLY: verify each finding against the real code first, fix ONLY the genuinely-correct
ones, and rebut + resolve false positives WITHOUT changing correct code. Repeat until no
unresolved Copilot comments remain. Use when the user says "satisfy Copilot", "clear the Copilot
review", "fix Copilot comments", "Copilot loop", or wants to iterate on Copilot PR feedback.
compatibility: GitHub only (Copilot code review is a GitHub feature). Requires git + jq + gh (GitHub CLI) authenticated, Copilot code review enabled, and permission to request reviewers on the repository.
metadata:
- version: "1.1"
+ version: "1.2"
allowed-tools: Bash(gh:*) Bash(git:*)
---
# Copilotloop
Drive a GitHub PR until Copilot has no unresolved review comments, **but do not cargo-cult its
suggestions.** Every comment is a *claim to verify*, not an instruction to obey. A wrong
suggestion applied is worse than the comment itself.
## How Copilot differs from other review bots
- **No check-run, no score.** Copilot posts an overview comment and a PR review with inline review
comments. Detection is by polling the reviews endpoint and paginated review threads. "Satisfied"
- means zero unresolved Copilot threads and zero unaddressed body findings after each finding is
+ means Copilot has reviewed the latest push, no bot thread is unresolved, and no body finding is unaddressed after each finding is
fixed or rebutted with a recorded reply.
- **Request through the reviewers API.** Copilot does not use a reliable slash-command trigger.
Request `copilot-pull-request-reviewer[bot]` through the pull request reviewers endpoint. A
repository may also be configured to review new pushes automatically.
- **Copilot may repeat comments.** A re-review can repeat comments that were resolved or downvoted,
so match findings to the current head and prior replies before reopening work, including body
findings that have no inline thread.
- **Copilot is concise and can reason from the diff alone.** Its characteristic failure is
confidently asserting a bug based only on the changed hunk, without the surrounding file or the
call sites. That makes "read the whole file before believing it" the single highest-value check.
## Not for
- GitLab / Perforce. For other review bots this catalog ships `codexloop`, `geminiloop`,
`coderabbitloop`, and `qodoloop`; for CI failures rather than review comments, use
`ci-fix-loop`.
## 0. Resolve the Copilot bot login (do this first)
The bot login is normally stable, but confirm it from the PR rather than assuming it:
```bash
gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate --jq '.[].user.login' | sort -u
gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate --jq '.[].user.login' | sort -u
```
Use `copilot-pull-request-reviewer[bot]` as `BOT`. Confirm it appears after the first requested
review; if GitHub uses a different login for the installation, use the exact Copilot-looking login
returned by the probe rather than guessing.
**Finding nothing here is NOT a stop condition.** On a PR Copilot has never reviewed there is no bot
- login to find yet. Fall through to step 2A, request the reviewer, and re-run this probe once a
+ login to find yet. Fall through to step A, request the reviewer, and re-run this probe once a
review lands. Only conclude Copilot is unavailable after the bounded wait expires with no review.
+ ## Review state comes from the PR, not from memory
+
+ `scripts/pr-review-state.sh` reads the PR and prints one JSON object: the current head, whether
+ Copilot has acted on that head (a review of it, or any comment after it was pushed), and every
+ unresolved review thread with its author. Every "is there work / are we done" decision in this
+ loop comes from its exit code, never from what you remember resolving. The script lives in this
+ skill's directory, `SKILL_ROOT`: the directory holding this `SKILL.md` (Claude Code prints it as the
+ skill's base directory when the skill loads; in Codex, derive it from the selected `SKILL.md` path).
+
+ | Exit | `verdict` | Meaning | Do |
+ |------|------------|---------------------------------------------------------------------|--------------------------------------|
+ | 0 | `clean` | Copilot acted on the current head and no bot thread is unresolved | exit check: done |
+ | 10 | `findings` | unresolved threads from Copilot **or any other review bot** | run an iteration |
+ | 20 | `pending` | Copilot has not acted on the current head yet | trigger if needed, then wait |
+ | 30 | `limited` | a rate-limit or paused notice from Copilot after the current head | stop, report `blocked: rate-limited` |
+
+ Resolving the last thread does not make a PR clean: Copilot has not reviewed your push yet. Earlier
+ versions of this loop exited at exactly that moment, while the next round of comments was still on
+ its way. Human threads are listed in `.unresolved` (`is_bot: false`) and counted in `.counts.humans`;
+ they never block `clean`, and this loop never resolves them.
+
## 1. Identify the PR
```bash
gh pr view --json number,headRefName,headRefOid -q '{number,branch:.headRefName,head:.headRefOid}'
```
Switch to the PR branch if not already on it. Capture `OWNER`/`REPO` (`gh repo view --json owner,name`).
## 2. The loop (max 5 iterations)
Keep an explicit iteration counter and stop at 5: the cap is a real bound to enforce, not a
figure of speech. Each pass through A–G is one iteration; on hitting the cap, go straight to the
report and list what is still unresolved rather than starting a sixth.
- ### A. Ensure a fresh Copilot review on the current head
-
- ```bash
- HEAD_SHA=$(gh pr view <PR> --json headRefOid -q .headRefOid)
- # Only trigger if no Copilot review exists for this exact SHA:
- HAVE=$(gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate |
- jq -s --arg bot "$BOT" --arg head "$HEAD_SHA" \
- '[.[][] | select(.user.login==$bot and .commit_id==$head)] | length')
- if [ "$HAVE" = "0" ]; then
- gh api --method POST repos/{owner}/{repo}/pulls/<PR>/requested_reviewers \
- -f 'reviewers[]=copilot-pull-request-reviewer[bot]'
- fi
- ```
+ ### A. Read the PR state; wait for Copilot's review of the current head
- Poll for the review of THIS head to land. No check-run exists, so poll the reviews endpoint, and
- poll it on a **deadline**, never `while true`: a review that never arrives must end the skill with
- an honest timeout, not hang it.
+ One read answers both "is there work?" and "has Copilot seen my last push?". `SINCE` is the
+ timestamp you took right before your last push (step E); leave it empty on iteration 1. Right
+ after a push, add `--wait 600` straight away: the wait ends only once the bot has acted on the new
+ head, so threads left open on purpose cannot make the push look reviewed.
```bash
- # 10-minute deadline, one retry, then give up. DEADLINE/RETRIES are the
- # enforcement of the bounds this skill claims: do not drop them.
- wait_for_review() { # $1 = attempt label
- local deadline=$(( SECONDS + 600 ))
- while [ "$SECONDS" -lt "$deadline" ]; do
- R=$(gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate |
- jq -s --arg bot "$BOT" --arg head "$HEAD_SHA" \
- '[.[][] | select(.user.login==$bot and .commit_id==$head)] | sort_by(.submitted_at, .id) | last')
- if [ -n "$R" ] && [ "$R" != "null" ]; then return 0; fi
- echo "waiting for Copilot review of $HEAD_SHA ($1)..."; sleep 15
- done
- return 1
- }
-
- if ! wait_for_review "first wait"; then
- echo "no Copilot review after 10m, retrying once" # say the retry out loud
- gh api --method POST repos/{owner}/{repo}/pulls/<PR>/requested_reviewers \
- -f 'reviewers[]=copilot-pull-request-reviewer[bot]'
- if ! wait_for_review "after retry"; then
- echo "Copilot did not review $HEAD_SHA after a retry; stopping and reporting."
- exit 1 # honest timeout, never a success claim
- fi
- fi
+ "$SKILL_ROOT/scripts/pr-review-state.sh" --repo OWNER/REPO --pr <PR> --bot copilot-pull-request-reviewer --since "$SINCE"
```
- Copilot usually reviews quickly, but large diffs can take longer; the deadline is bounded. Report the
- retry in the final summary; two silent timeouts are the failure mode this guard exists to prevent.
+ - Exit `10` (`findings`): go to B. On iteration 1 this is whatever Copilot (or another bot)
+ already posted.
+ - Exit `20` (`pending`): request it through the reviewers endpoint (`gh api --method POST repos/{owner}/{repo}/pulls/<PR>/requested_reviewers -f 'reviewers[]=copilot-pull-request-reviewer[bot]'`). Then wait with the same command plus `--wait 600`. Run the
+ wait in the background where the host allows it (Claude Code: Bash `run_in_background`; you are
+ re-invoked when it exits) so ten minutes of polling never sits in the conversation. Still `20`
+ after the wait: say so out loud, request the reviewer once more, and wait once more. Still `20` after that: stop and
+ report the timeout honestly; never claim success.
+ - Exit `0` (`clean`): go to the exit check. A `--wait` call returns `clean` only after a settle
+ re-read 60 seconds later, so a comment landing right behind the review is still caught. A bare
+ read (no `--wait`) that says `clean` is good enough only when you have not pushed since Copilot's
+ last review.
+ - Exit `30` (`limited`): stop now and report `blocked: rate-limited`; nothing more is coming.
+ - Exit `1`: the read itself failed (often a transient GitHub 502). Retry once; if it fails again,
+ stop and report it. An unknown state is not a clean one.
### B. Fetch the findings
+ The working set is every unresolved thread in the state JSON with `is_bot: true`: Copilot's
+ own (`is_target: true`) **and any other review bot's** (Greptile, for example). A
+ fix for one bot often draws a comment from another, and leaving those open is how a "finished" loop
+ leaves a PR that is not clean. Treat another bot's thread with exactly the same verify-first rules
+ below. Never act on a human's thread (`is_bot: false`); list it in the report.
+
- **Summary**: read the Copilot overview comment and review `.body`, including all matching reviews
for the current head. Extract and classify actionable claims even when they have no inline thread;
an approval assessment or lack of inline comments does not make those findings complete.
Track each body finding across iterations by source review/comment ID and item, with its
classification, fix commit or evidence-based rebuttal, PR-level reply URL, and completion status.
Link duplicates to the same finding so they are counted once; retain pending findings after a push.
- - **Unresolved inline comments** on the current head:
+ - **Unresolved inline comments**: `.unresolved[] | select(.is_bot)` in step A's state JSON lists
+ each thread's `thread_id`, `comment_id`, `path`, `line` and a short excerpt, across every page of
+ threads. Read the full comment before judging it:
```bash
- gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate \
- --jq ".[] | select(.user.login==\"$BOT\") | {id, path, line, body}"
+ gh api repos/{owner}/{repo}/pulls/comments/<COMMENT_ID> --jq '{user: .user.login, path, line, body}'
```
- Also pull the review threads + their resolved state via GraphQL (see step F) so you only act on
- unresolved ones.
-
Mark each unresolved inline comment as seen, so the bot and a watching human can tell it is being
handled. GitHub's reaction set is fixed; `eyes` is the only "looking at it" value:
```bash
gh api --method POST repos/{owner}/{repo}/pulls/comments/<COMMENT_ID>/reactions -f content=eyes
```
Body findings (no inline thread) have no comment to react to; track them in step B's register and
give each a PR-level reply in step F instead.
### C. Critically evaluate EACH finding (the core of this skill)
For every inline or body finding, **verify the claim against the actual code and repo conventions
before touching anything.** Read the whole file, not just the diff hunk Copilot saw, plus the types
and the call sites. Then classify:
1. **CORRECT + actionable**: the finding is real and the fix improves the code. → fix it (step D).
2. **FALSE POSITIVE / technically wrong**: the claim doesn't hold. → do **NOT** change code; write a
specific, evidence-based reply (cite the exact code/line/behavior that disproves it), then resolve
its thread or record completion for a body finding (step F).
3. **Valid but out-of-scope / stylistic nit** that conflicts with repo convention or the PR's intent
→ briefly decline with evidence of that convention or scope, then resolve its thread or record
completion for a body finding (step F). Do not expand the PR's scope to satisfy a nit.
**Hard rules:**
- **Never modify correct code just to silence Copilot.** Prefer a reasoned rebuttal.
- When uncertain whether a claim holds, **investigate** (read more code, run the type-checker / tests)
rather than assume Copilot is right. Default to skepticism.
- If a suggested change would break other call sites, alter public behavior, or contradict a verified
repo convention, it is a category-2 rebuttal, not a fix.
- Never fabricate identifiers to satisfy a comment (e.g. a Linear/ticket prefix). If Copilot asks for a
ticket reference and none exists, say so; do not invent one.
**Copilot's common failure modes to watch for (default these to category 2):**
- Diff-local reasoning: asserts a bug that the unchanged surrounding code already handles.
- "This can be null/undefined here" where the type or an earlier guard already rules it out.
- Invented race conditions or error paths with no actual trigger.
- Suggestions that compile-break or break other callers.
- Security/perf warnings with no exploit path or measurable cost.
- Restating library/framework semantics incorrectly.
- Style demands that contradict the repo's existing, consistent pattern.
### D. Apply fixes: category 1 only
Make the minimal correct change. Re-run the local gate if the repo has one (typecheck/tests) before
moving on.
### E. Commit and push FIRST, before resolving anything
Order matters. A resolved thread is a claim that the fix is on the branch, so the push has to
succeed before the claim is made: otherwise a failed commit or push leaves the PR unfixed with the
finding marked resolved, and nobody looks at it again.
If step D changed code:
```bash
# Stage ONLY the files your fixes touched: never `git add -A`, which sweeps up
# unrelated work and untracked secrets sitting in the worktree.
git status --short # look before you stage
git add <path> [<path>...] # the files named in the findings you fixed
git commit -m "address Copilot review feedback (copilotloop iteration N)"
+ SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ) # step A reads bot activity after this
git push
```
Author the commit per the repo's norms (e.g. the user's identity; no AI attribution if that is the
convention). Confirm the push actually landed before continuing:
```bash
git rev-parse HEAD
gh pr view <PR> --json headRefOid -q .headRefOid # must match
```
If they differ, stop: the fix is not on the PR, so nothing may be resolved yet.
### F. Reply to every addressed finding and resolve its inline threads
- Only now, with the fixes pushed, reply and resolve. Fetch unresolved threads, **following
- pagination**: a PR with more than 100 threads will otherwise look clean while unresolved findings
- sit on page two:
-
- ```bash
- # Loop until hasNextPage is false, passing endCursor back in as $cursor.
- CURSOR=null
- while : ; do
- PAGE=$(gh api graphql -F cursor="$CURSOR" -f query='
- query($cursor: String) {
- repository(owner: "OWNER", name: "REPO") {
- pullRequest(number: PR_NUMBER) {
- reviewThreads(first: 100, after: $cursor) {
- pageInfo { hasNextPage endCursor }
- nodes { id isResolved comments(first: 1) { nodes { databaseId author { login } path body } } }
- }
- }
- }
- }')
- echo "$PAGE" # collect nodes from every page before deciding the PR is clean
- PI='.data.repository.pullRequest.reviewThreads.pageInfo'
- [ "$(echo "$PAGE" | jq -r "$PI.hasNextPage")" = "true" ] || break
- CURSOR=$(echo "$PAGE" | jq -r "$PI.endCursor")
- done
- ```
+ Only now, with the fixes pushed, reply and resolve. Take thread and comment ids from step A's state
+ JSON (`.unresolved[]`): the script already follows pagination, so do not hand-roll a threads query.
Reply on a thread's comment via `gh api repos/{owner}/{repo}/pulls/<PR>/comments -f body="..." -F in_reply_to=<comment_id>`,
then resolve:
```bash
gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "THREAD_ID"}) { thread { isResolved } } }'
```
Then record the disposition of each inline finding as a reaction on Copilot's own comment: the
learning signal, and a visible marker for a human scanning the PR:
- 👍 (`+1`): the finding was accepted and fixed.
- 👎 (`-1`): the finding was rebutted as a false positive. **This is the correction signal.**
```bash
gh api --method POST repos/{owner}/{repo}/pulls/comments/<COMMENT_ID>/reactions -f content=+1
# rebutted finding:
gh api --method POST repos/{owner}/{repo}/pulls/comments/<COMMENT_ID>/reactions -f content=-1
```
Reply first, then react, then resolve: the reaction is not a substitute for the reply, and a
resolved thread with no reply loses the reasoning.
- Resolve a thread only for comments authored by `$BOT` that you have fixed or rebutted: never
+ Resolve a thread only for a bot comment in your working set (this bot's or another
+ review bot's) that you have fixed or rebutted: never
blanket-resolve, and never resolve a human reviewer's thread.
Threads you are **rebutting** need no push, so they may be replied to and resolved regardless of
whether step D changed code.
For each body finding, post a PR-level reply (for example, using
`gh pr comment <PR> --body-file <reply-file>`) identifying the source review/comment and item.
Record the pushed fix commit and validation, or an evidence-based rebuttal, including the reason
for declining an out-of-scope finding. Record the reply URL in the tracking entry before marking
it complete. One reply may cover multiple explicitly identified findings. Fixed body findings
require the same successful push check as fixed threads; rebuttals need no push. If a finding also
has an inline thread, that thread still requires a reply and resolution.
- ### G. Re-review
+ ### G. Back to A
- Pushing re-triggers Copilot when automatic review of new pushes is on; otherwise request Copilot again
- through the reviewers endpoint. Go back to **A**
- with the new head SHA. If step D changed nothing (all comments were rebutted), skip the push,
- ensure all Copilot threads are resolved and all tracked body findings have recorded PR-level
- replies and are complete, then exit.
+ Go back to **A**. After a push, A waits for Copilot's review of the new head (pushing re-triggers
+ it when auto-review is on; otherwise A triggers it). If this iteration changed no code (every finding
+ rebutted), there is no new head to wait for: A's fresh read says `clean` or shows what is still open.
## 3. Exit conditions
+ Decide from a fresh state read, never from what you remember resolving.
+
Stop when **any** is true:
- - Zero unresolved `$BOT` threads and zero pending body findings remain across iterations. Every
- finding was fixed or rebutted with evidence, every inline thread was replied to and resolved,
- and every body finding has a recorded PR-level reply. (There is no score to hit:
- this is "done".)
- - Max iterations (5) reached: report what remains.
- - Copilot never responded after one retry: report the timeout honestly; do not claim success.
+ - **Done**: the latest `pr-review-state.sh --wait 600` call, made after your last push, exited `0`
+ (`clean`); with no push since the bot's last review, a bare read that exits `0` is enough, and the body-finding register from step B has no pending entries. Open human threads do not block this; list them in the report.
+ - **Max iterations (5)** reached: report what remains.
+ - **Timeout**: still `pending` after the retry in step A. Report it honestly; do not claim success.
+ - **Rate limited**: exit `30`. Report `blocked: rate-limited`.
+ ## Keep the context small; resume instead of restarting
+
+ - Carry only three things between iterations: the iteration counter, the latest state JSON, and a
+ ledger of each thread you handled (fixed with its commit, rebutted, or blocked). Re-read files
+ fresh each iteration; do not re-paste earlier rounds' comment bodies.
+ - All loop state lives on the PR, so the loop is resumable. If the session has grown long or slow,
+ or a bot commented after the loop ended, run this skill again in a fresh session: step A picks up
+ from the PR as it is now. Starting fresh is cheaper than dragging a long session through more
+ rounds.
+ - After reporting done, if the host can schedule a follow-up (Claude Code: `/loop` or a scheduled
+ wakeup), offer one re-check about 20 minutes later for bots that comment late.
+
## 4. Report
```text
Copilotloop complete.
PR: #<n>
Bot login: <resolved $BOT>
Iterations: N
Findings fixed: N (inline + body findings, deduplicated)
Findings rebutted: N (inline + body findings, with recorded evidence-based replies)
- Remaining: 0 (unresolved inline + pending body findings, deduplicated)
+ Remaining: N (unresolved inline + pending body findings, deduplicated)
+ Human threads: N (open, listed below; this loop never resolves them)
+ Final state: clean | timeout | rate-limited | iteration cap
```
If it stopped at max iterations, list the remaining threads and body findings with your current
assessment (fix-pending vs disputed) so a human can arbitrate.