@olegkoval/agent-skills 1.49.2 → 1.51.0

package/adapters/grok/olko-github-pr/skills/coderabbitloop/SKILL.md

@@ -9,7 +9,7 @@ description: >
   CodeRabbit" / "resolve CodeRabbit comments".
 compatibility: Requires git and gh (GitHub CLI) authenticated, with the CodeRabbit GitHub App installed on the repo.
 metadata:
-  version: "1.0"
+  version: "1.1"
 allowed-tools: Bash(gh:*) Bash(git:*)
 ---
 <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
@@ -46,13 +46,30 @@ CodeRabbit has slash commands (official, `docs.coderabbit.ai/reference/review-co
 gh pr view --json number,headRefName,headRefOid -q '{number, branch: .headRefName, sha: .headRefOid}'
 ```
 
-Check out the branch if not already on it.
+Check out the branch if not already on it, **then require a clean working tree**
+(`git status --porcelain` empty) before touching anything:
+
+```bash
+[ -z "$(git status --porcelain)" ] || { echo "working tree not clean, refusing to start: would risk committing unrelated changes"; exit 1; }
+```
+
+This is the precondition step E's scoped `git add <file>` depends on: staging only the files a fix
+touched is safe *because* the tree started clean. Skip it and a file with pre-existing local edits
+gets those edits swept into the fix commit right along with it.
 
 ### 2. Loop (max 5 iterations)
 
-#### A. Push and wait
+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–F is one iteration; on hitting the cap, go straight to the report.
+
+#### A. Wait for a review of the current head
+
+On **iteration 1**, if there is nothing to push yet (you haven't fixed anything in this loop), don't
+wait for a brand-new review: use whatever CodeRabbit has already posted as your starting point and
+go straight to step B. Otherwise:
 
 ```bash
+SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 git push
 ```
 
@@ -62,11 +79,27 @@ If this repo doesn't auto-review on push, nudge it:
 gh pr comment <PR_NUMBER> --body "@coderabbitai review"
 ```
 
-Poll (every ~10s, timeout ~5min) for CodeRabbit's next formal review to land: a new entry in `gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/reviews` from `coderabbitai[bot]` created after this push. If you instead see a rate-limit comment ("review limit"), **stop the loop now** and go to Report with `blocked: rate-limited`.
+Poll (every ~10s, timeout ~5min) for CodeRabbit's next formal review to land: a new entry in
+`gh api --paginate repos/{owner}/{repo}/pulls/<PR_NUMBER>/reviews` from `coderabbitai[bot]`
+(REST spelling carries the `[bot]` suffix) created after `$SINCE`. Follow pagination so a review
+that lands on page two is not missed. If you instead see a rate-limit comment ("review limit"),
+**stop the loop now** and go to Report with `blocked: rate-limited`. If no review arrives within
+the timeout after one retry, stop and report the timeout honestly; do not claim success.
 
 #### B. Fetch unresolved findings
 
-Run the `unresolvedQodoThreads`-shaped query in `references/graphql-queries.md` (filter `author.login == "coderabbitai[bot]"` instead of Qodo's login). For each unresolved thread, parse the finding text and the **Prompt for AI Agents** block (heading text is `🤖 Prompt for AI Agents`, not `Agent Prompt`: match case/emoji-insensitively).
+Run the `unresolvedQodoThreads`-shaped query in `references/graphql-queries.md` (filter `author.login`
+on GraphQL's bare `coderabbitai`, **not** REST's `coderabbitai[bot]`: see the reference's login-spelling
+note, and follow `pageInfo.hasNextPage`/`endCursor` until exhausted). For each unresolved thread,
+parse the finding text, its `databaseId`, and the **Prompt for AI Agents** block (heading text is
+`🤖 Prompt for AI Agents`, not `Agent Prompt`: match case/emoji-insensitively).
+
+Mark each thread as seen with an 👀 reaction on its first comment (`databaseId` from the query), so
+the bot and a watching human can tell it is being worked:
+
+```bash
+gh api --method POST repos/{owner}/{repo}/pulls/comments/<DATABASE_ID>/reactions -f content=eyes
+```
 
 #### C. Check exit conditions
 
@@ -74,26 +107,68 @@ Stop if there are zero unresolved CodeRabbit threads, or max iterations reached.
 
 #### D. Fix each finding
 
-For each thread, in order: read the Prompt for AI Agents block in full: it names the issue and the fix. Apply it, staying inside its stated scope. If the suggestion is wrong, unsafe, or needs a product decision, don't force it: note that in step E instead.
+For each thread, in order: read the Prompt for AI Agents block in full: it names the issue and the fix. Apply it, staying inside its stated scope. If the suggestion is wrong, unsafe, or needs a product decision, don't force it: note that in step F instead. Track two lists as you go: **fixed** (thread id + the exact files you touched) and **skipped** (thread id + why). Do not resolve anything yet.
+
+#### E. Commit and push FIRST, before resolving anything
 
-#### E. Answer and resolve
+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.
 
-**Reply to the thread first, then resolve it**, the "answer to the comments" half of the job:
+If step D changed code:
 
 ```bash
-gh api graphql -f query='mutation { addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: "<THREAD_ID>", body: "<REPLY>"}) { comment { id } } }'
+# 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 CodeRabbit review feedback (coderabbitloop iteration N)"
+git push
 ```
 
-Reply body: one or two sentences, what you changed and why, or exactly why you didn't fix it. Then resolve (`resolveReviewThread`). A finding you deliberately skip still gets a reply and gets resolved.
+Confirm the push actually landed before continuing:
 
-#### F. Commit and push
+```bash
+git rev-parse HEAD
+gh pr view <PR_NUMBER> --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 each finding, react, then resolve
+
+Only now, with the fixes pushed, reply and resolve. **Reply to the thread first, then react, then
+resolve it**, the "answer to the comments" half of the job:
 
 ```bash
-git add -A
-git commit -m "address CodeRabbit review feedback (coderabbitloop iteration N)"
-git push
+gh api graphql -f query='
+  mutation($threadId: ID!, $body: String!) {
+    addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: $threadId, body: $body}) {
+      comment { id }
+    }
+  }' -f threadId="$THREAD_ID" -f body="$REPLY_TEXT"
 ```
 
+Pass the thread id and reply text as GraphQL **variables** (`-f threadId=... -f body=...`), never
+interpolated into the query string: a reply containing a quote, backtick, or newline breaks (or
+injects into) a hand-built query.
+
+Reply body: one or two sentences, what you changed and why, or exactly why you didn't fix it. A
+finding you deliberately skip still gets a reply and gets resolved.
+
+Then record the disposition as a reaction on the thread's first comment: the learning signal, and a
+visible marker for a human scanning the PR. 👍 (`+1`) for fixed, 👎 (`-1`) for skipped/rebutted.
+CodeRabbit reads a 👎 as feedback that the finding was wrong.
+
+```bash
+gh api --method POST repos/{owner}/{repo}/pulls/comments/<DATABASE_ID>/reactions -f content=+1
+# skipped/rebutted finding:
+gh api --method POST repos/{owner}/{repo}/pulls/comments/<DATABASE_ID>/reactions -f content=-1
+```
+
+Then resolve (`resolveReviewThread`). Reply first, react, then resolve: a reaction never replaces
+the reply, and a resolved thread with no reply loses the reasoning.
+
 Go back to step A.
 
 ### 3. Report
@@ -104,7 +179,7 @@ Go back to step A.
 | Findings resolved  | N     |
 | Findings skipped   | N (with reasons) |
 | Remaining          | N (if any) |
-| Blocked            | rate-limited / max-iterations / none |
+| Blocked            | rate-limited / timeout / max-iterations / none |
 
 ```
 Coderabbitloop complete.
@@ -115,4 +190,4 @@ Coderabbitloop complete.
 
 ## References
 
-- `references/graphql-queries.md`: shared with `qodoloop`: the exact `reviewThreads` query and the `resolveReviewThread` / `addPullRequestReviewThreadReply` mutations. Swap the author-login filter to `coderabbitai[bot]` and the prompt-heading match to `Prompt for AI Agents`.
+- `references/graphql-queries.md`: shared with `qodoloop`: the exact `reviewThreads` query (including the `databaseId` the reaction step needs) and the `resolveReviewThread` / `addPullRequestReviewThreadReply` mutations. Filter `author.login` on GraphQL's bare `coderabbitai` (never `coderabbitai[bot]`) and match the prompt heading `Prompt for AI Agents`.

package/adapters/grok/olko-github-pr/skills/coderabbitloop/references/graphql-queries.md

@@ -6,6 +6,15 @@ against CodeRabbit's own documentation (`docs.coderabbit.ai/reference/review-com
 plus a real `<!-- ... summarize by coderabbit.ai -->` comment observed live:
 not guessed.
 
+**The bot's login string is spelled differently in REST vs GraphQL.** REST
+(`.user.login` on `pulls/.../comments`) returns `coderabbitai[bot]`. GraphQL
+(`author.login` on `reviewThreads`) returns `coderabbitai`, no `[bot]` suffix
+(confirmed live against PR #114's own threads). Using the REST spelling in a
+GraphQL filter silently matches nothing, which reads as "no findings" instead
+of "wrong filter": exactly the kind of bug that has no crash and no error to
+notice. Use `[bot]` only in REST-based jq filters (`.user.login`); use the
+bare name everywhere you're filtering a GraphQL `author.login`.
+
 ## Fetch unresolved CodeRabbit threads (paginated)
 
 ```graphql
@@ -18,7 +27,7 @@ query($cursor: String) {
           id
           isResolved
           comments(first: 1) {
-            nodes { body path line author { login } }
+            nodes { databaseId body path line author { login } }
           }
         }
       }
@@ -27,12 +36,13 @@ query($cursor: String) {
 }
 ```
 
-Filter client-side to `coderabbitai[bot]` and `isResolved == false`:
+Filter client-side to GraphQL's `coderabbitai` (bare name, see the note above)
+and `isResolved == false`:
 
 ```bash
 gh api graphql -f query='...' --jq \
   '.data.repository.pullRequest.reviewThreads.nodes[]
-   | select(.comments.nodes[0].author.login == "coderabbitai[bot]")
+   | select(.comments.nodes[0].author.login == "coderabbitai")
    | select(.isResolved == false)'
 ```
 
@@ -53,14 +63,18 @@ description text above it: not every low-confidence nit gets one.
 
 ```bash
 gh api graphql -f query='
-mutation {
-  addPullRequestReviewThreadReply(input: {
-    pullRequestReviewThreadId: "THREAD_ID"
-    body: "REPLY_TEXT"
-  }) { comment { id } }
-}'
+  mutation($threadId: ID!, $body: String!) {
+    addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: $threadId, body: $body}) {
+      comment { id }
+    }
+  }' -f threadId="$THREAD_ID" -f body="$REPLY_TEXT"
 ```
 
+Pass the thread id and reply text as GraphQL **variables** (`-f`), never interpolated straight into
+the query string. A reply containing a quote, backtick, or embedded newline breaks (or, worse,
+injects into) a hand-built query string; `gh api graphql -f` handles the escaping correctly when the
+value travels as a variable instead.
+
 `pullRequestReviewThreadId` and `body` are the only required fields.
 
 ## Resolve a thread (batch)
@@ -81,6 +95,24 @@ marks every one of its threads resolved at once server-side. That's a valid
 bulk escape hatch if the user wants to blow through remaining low-value nits,
 but it skips the per-finding reply: don't use it as the default path.
 
+## React to a comment (the bot's learning signal)
+
+Reacting needs the comment's REST id, which is why `databaseId` is selected in
+the thread query above. The reaction set is fixed; only eight values exist:
+`+1`, `-1`, `laugh`, `confused`, `heart`, `hooray`, `rocket`, `eyes`.
+
+```bash
+# 👀 as soon as you start working a finding
+gh api --method POST repos/{owner}/{repo}/pulls/comments/<DATABASE_ID>/reactions -f content=eyes
+# 👍 when it was accepted and fixed, 👎 when it was rebutted (the correction signal)
+gh api --method POST repos/{owner}/{repo}/pulls/comments/<DATABASE_ID>/reactions -f content=+1
+gh api --method POST repos/{owner}/{repo}/pulls/comments/<DATABASE_ID>/reactions -f content=-1
+```
+
+React after the reply and before the resolve, so GitHub records the reason and
+the disposition together. A reaction never replaces the reply. CodeRabbit reads
+a 👎 on one of its comments as feedback that the finding was wrong.
+
 ## Fetch the walkthrough/summary comment (context only, not the source of truth)
 
 ```bash

package/adapters/grok/olko-github-pr/skills/codexloop/SKILL.md

@@ -6,9 +6,9 @@ description: >
   ones, and rebut + resolve false positives WITHOUT changing correct code. Repeat until no
   unresolved Codex comments remain. Use when the user says "satisfy codex", "clear the codex
   review", "fix codex comments", "codex loop", or wants to iterate on Codex PR review feedback.
-compatibility: GitHub only (Codex code review is a GitHub app). Requires git + gh (GitHub CLI) authenticated, and the Codex / ChatGPT connector app installed on the repo with code review enabled.
+compatibility: GitHub only (Codex code review is a GitHub app). Requires git + jq + gh (GitHub CLI) authenticated, and the Codex / ChatGPT connector app installed on the repo with code review enabled.
 metadata:
-  version: "1.1"
+  version: "1.2"
 allowed-tools: Bash(gh:*) Bash(git:*)
 ---
 <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
@@ -37,7 +37,7 @@ suggestion applied is worse than the comment itself.
 ## Not for
 
 - GitLab / Perforce (Codex code review is a GitHub app). For other review bots this catalog ships
-  `geminiloop`, `coderabbitloop`, and `qodoloop`; for CI failures rather than review comments, use
+  `copilotloop`, `geminiloop`, `coderabbitloop`, and `qodoloop`; for CI failures rather than review comments, use
   `ci-fix-loop`.
 
 ## 0. Resolve the Codex bot login (do this first, do not hardcode)
@@ -84,9 +84,13 @@ report and list what is still unresolved rather than starting a sixth.
 
 ```bash
 HEAD_SHA=$(gh pr view <PR> --json headRefOid -q .headRefOid)
-# Only trigger if no Codex review already exists for this exact SHA:
-HAVE=$(gh api repos/{owner}/{repo}/pulls/<PR>/reviews --paginate \
-  --jq "[.[] | select(.user.login==\"$BOT\" and .commit_id==\"$HEAD_SHA\")] | length")
+# Only trigger if no Codex review already exists for this exact SHA.
+# gh cannot combine --slurp with --jq, so pipe to `jq -s`: it folds every page
+# into one array. Without it the filter runs once per page and HAVE becomes a
+# multi-line count that never equals "0", silently skipping the trigger.
+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 pr comment <PR> --body "@codex review"; fi
 ```
 
@@ -100,8 +104,9 @@ an honest timeout, not hang it.
 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 "[.[] | select(.user.login==\"$BOT\" and .commit_id==\"$HEAD_SHA\")] | last")
+    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 Codex review of $HEAD_SHA ($1)..."; sleep 15
   done
@@ -135,6 +140,13 @@ gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate \
 Also pull the review threads + their resolved state via GraphQL (see step F) so you only act on
 unresolved ones.
 
+Mark each unresolved 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
+```
+
 ### C. Critically evaluate EACH comment (the core of this skill)
 
 For every comment, **verify the claim against the actual code and repo conventions before touching
@@ -236,6 +248,21 @@ then resolve:
 gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "THREAD_ID"}) { thread { isResolved } } }'
 ```
 
+Then record the disposition as a reaction on the bot'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
 blanket-resolve, and never resolve a human reviewer's thread. For each fixed comment, verify the
 push first, reply with the change made, then resolve the thread and verify `isResolved: true`.

package/adapters/grok/olko-github-pr/skills/copilotloop/SKILL.md

@@ -0,0 +1,309 @@
+---
+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"
+allowed-tools: Bash(gh:*) Bash(git:*)
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# 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
+  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
+review lands. Only conclude Copilot is unavailable after the bounded wait expires with no review.
+
+## 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
+```
+
+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.
+
+```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
+```
+
+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.
+
+### B. Fetch the findings
+
+- **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:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate \
+  --jq ".[] | select(.user.login==\"$BOT\") | {id, 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)"
+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
+```
+
+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
+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
+
+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.
+
+## 3. Exit conditions
+
+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.
+
+## 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)
+```
+
+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.