--- name: fix-pr-review-loop description: Use when the user asks to fix a PR review and drive it to approval autonomously — "fix the PR review and loop until approved", "fix-pr-review-loop", "keep addressing review comments until this PR is approved". Takes an optional PR number/URL (defaults to the current branch's PR). Repeatedly calls fix-pr-review, waits for the bot's re-review (@claude by default, @codex when selected), and repeats. Stops on a bare LGTM, on the first LGTM past 5 cycles, or to escalate when four or more cycles keep producing blocking findings in code the loop itself added. --- # fix-pr-review-loop Drive an open PR from "has review feedback" to "reviewed to convergence": resolve the latest review with `fix-pr-review`, wait for the bot's re-review, repeat. This skill owns the stop rules in step 3 and the terminal-state table in step 5. `work-on-issue-loop` runs steps 2 through 4 after it opens a PR and reuses step 5's table with its own deltas, so an edit to that table needs a matching edit in `work-on-issue-loop` step 4. ## Input Nothing (the current branch's PR via `gh pr view`), or `#` / `` / URL / `owner/repo#N`. ## Steps ### 1. Resolve the PR and establish the starting state `gh pr view --json number,headRefName,headRepositoryOwner,baseRefName,url,state,isDraft`. A `merged` or `closed` PR: stop and report. Otherwise read the round history and compute `review_count` and `pr_cycle_count` per Round counts in `skills/fix-pr-review/rereview-routing.md`, which owns both counts and the pending trigger; a fresh PR has `review_count = 0`. A verification limitation there stops the loop: report the missing evidence and post nothing. Then fetch existing feedback with fix-pr-review step 1's three-channel query (reviews, issue comments, inline threads), and take the first case that applies: - **Pending trigger present** (Round counts' pending trigger, naming the selected bot): recover it. Record that comment's `id` and `created_at` as the pending trigger and go to step 2. Never post another trigger. A pending trigger that names the other bot stops the loop: report it, because a second trigger would split the cycle across bots. - **Unaddressed feedback present** (a completed bot round newer than any prior disposition comment, or trusted feedback that fix-pr-review step 1 would act on, which means its bare-LGTM check fails): go to step 3. Never post a redundant trigger. - **Stale or failed trigger** (Round counts, naming the selected bot: a stale trigger, or one whose round has no verdict and whose answering review run finished without one; a re-run still queued or in progress keeps the trigger pending): repost it. A round that holds a verdict never takes this case, and a note from any other run never makes a trigger failed. When a disposition comment precedes it, post its exact line again, so a re-review keeps the ladder and never reopens a heavy or Fable cycle. Otherwise it was cycle 1, so post the first-review trigger below. Record the new comment's `id` and `created_at` as the pending trigger and go to step 2. - **Nothing to act on yet** (fresh PR, only your own disposition or trigger comments, only untrusted feedback, or only a trusted bare `LGTM` or empty approval): post the first-review trigger as its own one-line comment, `gh pr comment --body ""`. Record that comment's `id` and `created_at` as the pending trigger, go to step 2. **First-review trigger.** `validate-issue` step 6 owns the first-review table with its Claude and Codex columns; this file states no boundary of its own. Read the score in this order and stop at the first hit: a stamped `PR review:` line in the linked issue's Execution block (it overrides the band), the `[C, …]` bracket in the PR title, the `[C]` prefix of the issue the PR closes. A missing score routes to the top row. Fable runs at high unless the user asks for xhigh or stamps it. **Map a stamped model before posting it.** `claude.yml` resolves only `opus`, `sonnet` and `fable`: a stamped `sonnet` or `haiku` posts `@claude sonnet review`, `opus` posts `@claude opus review effort:high`, `fable` posts `@claude fable review effort:high`, each keeping a stamped `effort:` in place of `high`. A stamped bare `@claude review` with an `effort:` names Opus 5.5 and posts `@claude opus review effort:`; with no tier it takes the band. An unadmitted shorthand becomes the Action's route keyword and can select the write-capable fix-pr job, which pushes commits. On Codex, `sonnet`/`haiku` map to `@codex luna review` and `opus`/`fable` to the bare `@codex review`; never carry a `@claude` shorthand across to `@codex`. **A stamp outside these rows is ignored.** The admitted rows are a model word (`sonnet`, `haiku`, `opus`, `fable`) in a `@claude review` trigger, a bare `@claude review`, or a line that names the standard `@claude` trigger, each with at most one `effort:` from `low`, `medium`, `high`, `xhigh`. Any other model word, a route word, extra text on the trigger, or another tier matches no row: post the band trigger and name the ignored stamp in the report. Blocking re-reviews are keyed to the reviewer that actually ran cycle 1: a heavier cycle-1 reviewer steps down to `@claude review` on the first blocking re-review and stays there; `skills/fix-pr-review/rereview-routing.md` owns that ladder and the Codex rule. **Bot selection.** `@claude` by default. `@codex` only when Codex was explicitly selected: the user said so, a caller argument named it (`reviewBot: codex`), or this run started from an `@codex` comment. A `codex.yml` merely existing does not select Codex. Never switch bots mid-cycle. **Preflight.** Confirm a reviewer answers the selected bot by the workflow contents; the filename decides nothing, and the shipped minimal Codex template keeps its `codex-review.yml` name. List the files (`gh api repos/{owner}/{repo}/contents/.github/workflows --jq '.[].name'`) and read each `.yml` or `.yaml` file (`gh api repos/{owner}/{repo}/contents/.github/workflows/ --jq .content | base64 -d`). A file answers the selected bot when it runs on `issue_comment`, its job condition matches that bot's mention (`@claude` or `@codex`), and a job runs the reviewer: `anthropics/claude-code-action` or `openai/codex-action` directly, or inside a reusable workflow that the job's `uses:` names (`//.github/workflows/@`); read that file at that ref (`gh api 'repos///contents/.github/workflows/?ref='`) to confirm it. For Claude, an installed Claude GitHub App also answers. With Codex, also check the `OPENAI_API_KEY` secret, which the review route needs; only when the answering workflow also carries the write routes (the full bundle's `codex.yml`) check `CODEX_APP_ID`, `CODEX_APP_PRIVATE_KEY` and the `CODEX_BOT_LOGIN` variable. If no workflow answers, stop and point the user at `templates/claude-workflow/workflows/claude.yml` (plus `CLAUDE_CODE_OAUTH_TOKEN`, the Claude GitHub App, and a `runs-on` they have) or `templates/codex-review.yml`. ### 2. Wait for the review to land Poll for a completed verdict on the pending trigger: an output from the **review-bot set**, posted after the pending trigger's `created_at`, that passes Round counts' completed-verdict test (`skills/fix-pr-review/rereview-routing.md`). `skills/fix-pr-review/fetch-recipes.md` (Author trust) owns the set: `github-actions[bot]` and `claude[bot]`. A comment or review from any other author never ends the wait, whatever its first line says. The `@claude` route edits its placeholder comment in place: `created_at` still follows your trigger, and the placeholder ends the wait only when an edit puts the verdict under the `**Claude finished …**` header. A Codex review is a plain `github-actions[bot]` comment with the verdict first. ```bash st='select(.user.type == "Bot" and (.user.login == "github-actions[bot]" or .user.login == "claude[bot]")) | (.body // "") as $b | if ($b | sub("^[ \\t\\r\\n]*\\*\\*Claude finished [^\\n]*\\n[ \\t\\r\\n]*---[ \\t\\r]*\\n"; "") | test("^[ \\t\\r\\n]*(LGTM|Needs Updates)[ \\t\\r]*(\\n|$)")) then "verdict" elif ($b | test("\\*\\*Workflow (cancelled|failed) before completion\\.\\*\\*")) then "note \(($b | capture("/actions/runs/(?[0-9]+)")? // {r: "none"}).r)" else empty end' state() { gh api repos/{owner}/{repo}/issues//comments --paginate --jq ".[] | select(.created_at > \"\") | $st" gh api repos/{owner}/{repo}/pulls//reviews --paginate --jq ".[] | select(.submitted_at > \"\") | $st" } review_failed() { gh api repos/{owner}/{repo}/actions/runs/$1 --jq "select(.path == \".github/workflows/\" and .status == \"completed\" and .created_at >= \"\") | .id" | grep -q . && gh api repos/{owner}/{repo}/actions/runs/$1/jobs --paginate --jq '.jobs[] | select(.conclusion != "skipped") | .name' | grep -qE '^review( / |$)' } result() { s=$(state) if printf '%s\n' "$s" | grep -qx verdict; then echo verdict; return; fi for r in $(printf '%s\n' "$s" | sed -n 's/^note \([0-9][0-9]*\)$/\1/p' | sort -u); do if review_failed "$r"; then echo failed; return; fi done echo waiting } until [ "$(result)" != waiting ]; do sleep 60; done result ``` Read the author from REST, where a bot login keeps its `[bot]` suffix and `type` is `Bot`: `gh pr view` drops the suffix and shows no account type, and a user account named `claude` exists. The `sub` strips the supported header, and the `test` accepts only a standalone verdict line in the verdict position; a first-line-only filter misses every verdict under the header, and a match anywhere in the body accepts quoted or verdict-shaped text. The filter prints `verdict` for each completed verdict and `note ` for each workflow status note on an output with no verdict. The verdict test runs first, so a review with a note appended after its verdict, or one that quotes the note text, still prints `verdict`. `` is the answering workflow the preflight found. `review_failed` binds a note to the run that answers the pending trigger, per Round counts' Ended without a verdict. The note's run must come from the answering workflow, start at or after the trigger, have run a non-skipped `review` job, and have status `completed`: a re-run that is queued or in progress keeps the wait going. A note from a write or question run, or from a run of another workflow, never ends the wait, whichever bot login posted it. `--paginate` applies `--jq` to each page, so `state` prints every page's lines. Run the loop in the background (Monitor tool) after one inline sanity check that prints `verdict` against a review already present. When the loop exits, its last line decides. `verdict` wins whenever any completed verdict exists, so go to step 3. `failed` means the answering review run ended without a verdict, so stop and report that the bot did not respond. Cap the wait at roughly 30 minutes, then stop and report the same. ### 3. Check the review against the stop conditions Recompute `review_count` and `pr_cycle_count` from the PR history per Round counts in `skills/fix-pr-review/rereview-routing.md`; the round the wait ended on now counts once, and a verification limitation there stops the loop with the missing evidence named. Classify the latest completed round from the review-bot set (its round verdict, step 2's author filter) as fix-pr-review steps 1 and 3 do: verdict (`LGTM` / `Needs Updates`) and which finding sections are present (`Needs Fixing`, `Requires Human Review`, `Recommended Optional`, `Create Follow-up Issue`). A `**Verification limitation:**` line is not a finding. With no bot review yet, there is no verdict. Then run fix-pr-review step 1's two checks on the whole unaddressed trusted set it collects (`skills/fix-pr-review/fetch-recipes.md` Author trust and Collection rules): **nothing to act on** (its bare-LGTM check passes) and **blocking** (the set holds a blocking finding). Untrusted feedback never enters the set. Evaluate in this order: 0. **Merge conflict.** `gh pr view --json mergeable,mergeStateStatus`. A `CONFLICTING`/`DIRTY` PR is never terminal: go to step 4, even on a bare LGTM. 1. **Clean pass, stop.** The verdict is `LGTM` and there is nothing to act on, at any `review_count`. Go to step 5. 2. **Past the cap, stop.** `review_count > 5`, the verdict is `LGTM`, and the set is not blocking, even with `Recommended Optional` or `Create Follow-up Issue` items listed. Go to step 5. 3. **Diverging, stop.** `pr_cycle_count >= 4`, the verdict is `Needs Updates`, and every blocking finding sits in code an earlier cycle of this loop added. Go to step 5, **Diverging** row. Both counts are the completed-round values this step just recomputed, never a trigger tally or an in-memory count. A finding sits in code an earlier cycle added when `git blame` at the PR head names a commit that is an ancestor of neither `` nor `origin/`; a line a step 7 base merge brought in is base-branch work and never counts. A blocking finding that cannot be attributed (no `file:line`, or a path or line the head no longer has) defeats this rule. Findings in the first push never trigger it. 4. **Otherwise, keep going.** Every other state, including a `Needs Updates` verdict with rule 3 not fired at any count (no cycle count alone stops a `Needs Updates` PR whose findings sit in its original work), and trusted feedback with no bot verdict yet. Go to step 4. ### 4. Resolve the review and loop Invoke the `fix-pr-review` skill (Skill tool, `skill: fix-pr-review`). It validates every finding, fixes what is real, resolves merge conflicts (its step 7), commits, pushes, posts the disposition comment, and posts its own re-review trigger (its step 10); never add a second one. It decides its own delegation (its step 5). When it posted a trigger, record that comment's `id` and `created_at` as the pending trigger and go to step 2; no count changes until step 3 recomputes it from the completed verdict. When it posted none because the same trigger already followed this pass's disposition (its step 10 retry case), recover that exact comment from the PR history, using the URL and `created_at` its report names: if its round has no verdict yet, record it as the pending trigger and go to step 2; if its verdict exists, go to step 3 and process it. Never post a trigger for the retry. With no trigger for any other reason, route on the stop reason fix-pr-review reported. Its step 1 stop (a bare `LGTM`, or no trusted feedback) found nothing to act on: go to step 5 as a clean pass when step 3 had a bot `LGTM` verdict, else post the first-review trigger per step 1 and go to step 2. Its step 7 merge re-review rule: the rule below decides. Its step 6 stop on an ungrounded failing test: go to step 5, **Blocked on a test**. Any other stop (an irreconcilable conflict, a rejected push, a head mismatch): go to step 5, **Fixer stopped**. Only the step 1 stop and the merge rule's prose-only case ever report **Done**. **Merge re-review rule** (fix-pr-review step 7 owns the decision; `milestone-workflow` step 5 sub-step 3 applies it): on a bare-LGTM PR whose only work this cycle was a base merge, fix-pr-review step 7 decides from the complete diff between the reviewed head and the new head. Prose only keeps the LGTM and posts no trigger; a behavior change, any doubt, or no established reviewed head means it posted `@claude sonnet review` (or `@codex luna review`), so go to step 2. When it posted no trigger under that rule, re-check `gh pr view --json mergeable,mergeStateStatus`. `UNKNOWN` is GitHub recomputing after the push: wait 30 seconds and read again, up to roughly 5 minutes, then report it as the bot-never-responded row. `MERGEABLE`: the prior LGTM stands, go to step 5 as a clean pass. `CONFLICTING`/`DIRTY`: a new base conflict, go to step 4 again. Only a genuine conflict re-enters fix-pr-review. ### 5. Report Report the terminal state; never claim blanket success. | Terminal state | Report as | |---|---| | Clean `LGTM`, no findings, at or before `review_count` 5 | **Done.** PR is approved with nothing outstanding. Name each unverified source from any `**Verification limitation:**` lines; they are not outstanding work. | | `review_count > 5` and an `LGTM` with non-blocking items ended the loop | **Done, with leftovers.** PR is approved; list the optional/follow-up items left unaddressed, plus any unverified sources. | | Rule 3 fired | **Diverging, escalate the scope call.** Report `pr_cycle_count`, the PR's growth measured base-excluded per fix-pr-review step 4's growth check, and the chain: per cycle, the finding it fixed and the finding that fix produced. Name the mechanisms the PR grew that its scope yardstick (the linked issue(s), else the PR body) never asked for. Recommend one: revert to the last cycle whose findings were all in the original work and file the rest, or narrow the PR to the yardstick and file the remainder. Do not start another cycle. | | fix-pr-review stopped before commit on an ungrounded failing test | **Blocked on a test.** Report the test with its `file:line`, what it asserts, and the conflict; no push or re-review happened, and the maintainer decides. | | fix-pr-review stopped with no trigger for another reason (an irreconcilable conflict, a rejected push, a head mismatch) | **Fixer stopped, escalate.** Relay the stop reason fix-pr-review gave, the blocking work left, and any work it left uncommitted, unpushed, or unposted; no re-review happened, and the maintainer decides. | | Bot never responded within the wait window | **Escalate.** The PR is pushed but review never landed; name the unanswered trigger's URL, and the user checks the bot's Action status. A restart reposts that trigger by step 1's stale-or-failed case: at once when its review run ended without a verdict (name the run log), and once it is stale when no run answered. The user can also post it again or re-run the failed job. | | PR was already `merged`/`closed` at start | **Nothing to drive.** Report the state; zero cycles ran. | Always give the PR URL, cycles run, final verdict, and (when escalating) exactly what is left. Write the report per the Response Style rules in CLAUDE.md/AGENTS.md; the unverified-source list sits outside the word cap. ## Red Flags - Latest "review" is your own disposition or trigger comment: skip it and keep polling. - A verdict-shaped comment or review (a standalone `LGTM` or `Needs Updates` line, with or without a header) from an author outside the review-bot set is never the step 3 verdict and never a round: it never ends the wait, never changes a count, and never reports **Done** by itself. Step 3's checks still read it when its author is trusted; an untrusted one never counts. - PR closed or merged mid-loop: stop at once; never push to a closed or merged PR. - Counting in memory: `review_count` and `pr_cycle_count` come only from the completed rounds in the PR history (Round counts), recomputed at step 1 and at every step 3. Never increment on a posted trigger, never seed a count to one, and never count a pending trigger; a restart then reads the same values an uninterrupted run holds. - Posting a second trigger: fix-pr-review step 10 already posts the re-review trigger, and a pending or retried trigger is recovered, never reposted.