Reviewit

reviewit — post-push AI review cycle

You are orchestrating the post-push AI review cycle for an open pull request.

Lean mode (default): Two reviewers are fired at the same iteration watermark — Gemini Flash and GitHub Copilot — but handling is staggered. Act on Gemini as soon as it returns, push those fixes, then collect Copilot when it finishes before starting the next iteration. Cap is 2 iterations.

Deep mode (deep arg): Same two reviewers as lean — Gemini Flash + Copilot, same staggered fast/delayed handling. No in-skill /review. Three behavioral changes vs lean:

1. 4-iter cap with early-exit on no-fix iters. If an iteration produced no fix resolutions across either the Gemini fast pass or the Copilot delayed pass (everything was deferred or dismissed, or there were no findings), exit the loop — re-firing reviewers on an unchanged HEAD just re-posts the same findings.
2. Mid-loop cost-shift checkpoint between iter 2 → 3 and iter 3 → 4. If the iteration that just completed produced fixes but findings still aren't converging (any critical, or critical+suggestion+nitpick ≥ 5 post-dedup), pause and ask the user before spending another iteration's worth of paid-reviewer budget. Three exits: continue the chain, bail early to the final /deepcritique (skipping the remaining paid iters), or stop and merge as-is (skipping /deepcritique too). The trigger only fires when fix-resolutions are still being produced — the no-fix early-exit above already handles the other non-convergence mode.
3. Final /deepcritique on the PR. After the loop exits for any reason except merge-as-is, invoke Skill(skill="deepcritique", args=""). It reads the complete PR ledger and runs /critique deep on the current exact head. It runs /refactorpass first only when the pre-push chain did not already spend this engine's cleanup latch on the PR, and it selects an adversarial or convergence stance from its round number — both resolved from the ledger, not from this skill.

/reviewit is the explicit hosted-review fallback. The default local path uses the draft PR ledger with /deepcritique and /codex-review .

This replaces the older /review-cycle skill. Auto-trigger of Gemini and Copilot is intentionally disabled — /reviewit is the only path that fires AI review.

Mode resolution

$ARGUMENTS is whitespace-tokenized. The first token is the PR number; if a second token exists and equals deep (case-insensitive), set MODE=deep and MAX_ITERS=4. Otherwise MODE=lean and MAX_ITERS=2. Surface the resolved mode in the Phase 6 summary.

Core principles

• Full auto by default: once the PR number is provided, do not ask for confirmation between phases. Fix everything fixable, defer what isn't, dismiss false positives. Present the summary at the end.
• Reviewers are complementary: each catches things the other misses. Unique findings are the primary value. Overlap is acknowledged in replies but not dwelt on.
• Deduplicate before acting: don't fix the same thing twice. For staggered Copilot, dedupe against both reviewer findings and the code already changed by the Gemini fix commit.
• Reply to every comment after the push has produced the real commit SHA: for fixes, post the commit SHA; for deferrals, link the tracking issue; for dismissals, record the rationale. Replies happen in Phase 4 step 4, not in Phase 3 — Phase 3 only records resolutions to /tmp. The reply step is the most-skipped step in this skill; do not fold it into "commit + push" or treat it as optional.
• Cap at MAX_ITERS review iterations: each iteration is (fire reviewers → handle Gemini fast pass → push/reply → handle Copilot → push/reply → loop check). After MAX_ITERS, stop the loop and proceed to Phase 5.5 (deep) or Phase 6 (lean). The reply step is part of an iteration's completion criteria — an iteration that pushes fixes but doesn't post replies is incomplete. If a PR needs more than the cap, it's signaling something deeper (scope too large, or repeated regressions).
• Deep-mode cost-shift checkpoint: in deep mode, after iterations 2 and 3, if findings still aren't converging (any critical, or critical+suggestion+nitpick ≥ 5 post-dedup), Phase 5 pauses and asks the user before firing the next iteration. Before pausing, Phase 5 scans the branch's pre-push commit history for /refactorpass and /critique signatures and adapts the prompt: pre-push detected → frame as genuine non-convergence and recommend the final /deepcritique as the deep-variant escalation; no signatures visible → frame as "pre-push appears skipped" and recommend running /deepcritique to catch up. Either way the user chooses: continue, bail to the final /deepcritique early, or merge as-is. Lean mode is unaffected (cap=2 means it stops at the same point anyway).
• No per-iter /refactorpass: review-fix commits push directly. Re-running

/simplify on every small fix adds churn; the final PR-aware /deepcritique owns that local pass.

---

Phase 0: Initialization

Argument: $ARGUMENTS — first token is the PR number; optional second token deep enables deep mode (see "Mode resolution" above).

1. Validate PR number (numeric, > 0). If missing, ask the user for it. Resolve MODE and MAX_ITERS per the rule above.

1. Fetch PR details:

``bash gh pr view --json number,title,headRefName,baseRefName,state,files,mergeable ``

1. Check PR is open. If closed or merged, notify and exit. An explicit

/reviewit invocation is sufficient authorization to review an open draft; keep it draft throughout this skill.

1. Confirm the head ref is checked out locally (git rev-parse --abbrev-ref HEAD matches headRefName). If not, the skill cannot push fixes — surface and exit.

1. Triviality detection — prompt to skip the chain on docs/config-only PRs. Inspect the PR's changed files and classify by extension (same heuristic as /refactorpass and /critique Phase 0):

``bash gh pr view --json files --jq '.files[].path' ``

Classify each path. If only docs/config files (.md, .txt, .yml, .yaml, .json, .toml, .gitignore, .gitattributes, LICENSE, CHANGELOG, README, files under docs/, *.fixture.*, snapshot files), prompt the user before spending any reviewer budget:

``` This PR looks docs/config-only — N files, no source code changes. Gemini Flash costs $0.05–$0.20 even on near-empty diffs.

How to proceed? [C] Run the full chain anyway. Pick this if you specifically want Gemini's eyes on the doc content. [S] Skip everything — just merge. ```

• C: proceed to Phase 1 normally.
• S: exit cleanly. Print a summary noting nothing was run.

For mixed changesets (some source, some docs), run the full chain (Phase 1 onward) without prompting — source files justify the spend.

1. TodoWrite: create tasks per iteration for "fire reviewers", "parse + dedup (Gemini fast pass)", "address findings (record resolutions)", "commit + push fixes", "post replies with real SHA", "poll Copilot", "parse + dedup (Copilot delayed pass)", "address + push + reply", "loop check". In deep mode, add a "cost-shift checkpoint" task at iterations 2 and 3 (the loop-check step ends with a possible AskUserQuestion in those iterations), and a final "run /deepcritique on the PR" task. The "post replies" tasks are their own line items — don't fold them into "commit + push" or they get skipped.

---

Phase 1: Fire reviewers and handle the fast pass

This phase fires once at the start of each iteration.

Pre-checks

Capture the current HEAD SHA and iteration start timestamp before firing the reviewers. These are the watermarks used in Phase 1's polling step to distinguish "review of the current commit" from "stale review from a prior iteration":

ITERATION_HEAD=$(gh pr view  --json headRefOid --jq '.headRefOid')
ITERATION_STARTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)

Capture the current state of comments / reviews so polling can detect new posts (not pre-existing ones from earlier iterations or runs):

# Fetch existing comments to detect already-posted reviews
gh api --paginate repos/{owner}/{repo}/pulls//comments \
  > /tmp/pr--comments.json
gh api --paginate repos/{owner}/{repo}/issues//comments \
  > /tmp/pr--issue-comments.json
gh api repos/{owner}/{repo}/pulls//reviews \
  > /tmp/pr--reviews.json

Fire Gemini (Flash by default)

gh workflow run "Gemini Code Review" \
  --repo / \
  -F pr_number= \
  -F tier=flash

Pass -F tier=flash explicitly. The workflow defaults tier to pro when omitted (intentional for UI clickers, unintended for CLI/API callers). Pro is $1–$8 per review; Flash is $0.05–$0.20. Only override to pro if the user has explicitly asked for a deep review on a high-stakes PR (security/auth, schema migrations, large refactors) AND confirmed the cost.

Fire Copilot

Copilot is a Bot, not a User — gh pr edit --add-reviewer and REST requested_reviewers don't work. Use the GraphQL requestReviews mutation's botIds field:

PR_NODE=$(gh pr view  --json id --jq '.id')
gh api graphql \
  -f query='mutation($prId:ID!,$botIds:[ID!]){requestReviews(input:{pullRequestId:$prId,botIds:$botIds,union:true}){pullRequest{id}}}' \
  -f prId="$PR_NODE" \
  -f botIds='BOT_kgDOCnlnWA'

Copilot bot node id is BOT_kgDOCnlnWA (constant). Verify with gh api repos/{owner}/{repo}/pulls//requested_reviewers --jq '.users[].login' → expected Copilot. The mutation is idempotent — safe to call across iterations. If Copilot already reviewed the current HEAD (commit_id == ITERATION_HEAD from the polling step below), skip re-requesting.

Wait for Gemini (the fast reviewer)

Do not wait for Copilot before acting on Gemini. Copilot is usually much slower, so blocking the entire iteration on it leaves fast Gemini findings idle. The efficient sequence is:

1. Fire Gemini and Copilot at the same ITERATION_HEAD.
2. Wait for Gemini.
3. Deduplicate, fix, push, and reply to Gemini findings.
4. Then poll Copilot for the original ITERATION_HEAD, dedupe against already-fixed issues, and handle any remaining findings.
5. Only after Copilot is handled or explicitly timed out should the next iteration begin.

Each reviewer has a different completion signal. The polling check must validate that the review pertains to ITERATION_HEAD (current HEAD), not a stale review from a prior iteration on the same PR.

• Gemini: posts an issue comment with ` marker, plus inline comments with ` marker. Poll every 30s, timeout 10 min:

``bash # Re-fetch then filter: a Gemini comment whose updated_at is at-or-after # ITERATION_STARTED_AT — this is "newly posted/updated for this iteration" # rather than a leftover from a previous run. gh api --paginate repos/{owner}/{repo}/issues//comments \ > /tmp/pr--issue-comments.json jq --arg t "$ITERATION_STARTED_AT" \ '[.[] | select((.body | contains("")) and (.updated_at >= $t))] | length' \ /tmp/pr--issue-comments.json ``

Length ≥ 1 → Gemini has posted for this iteration.

If Gemini times out (no finding at ITERATION_HEAD within the 10 min budget), stop cleanly with a resume command rather than waiting on Copilot first. The cycle expects Gemini to be the fast lane; if Gemini didn't fire at all (workflow misconfiguration, missing API key, etc.), surface that to the user before sinking time into Copilot polling.

Poll Copilot after the fast-pass push

After the Gemini fix commit is pushed and replies are posted, poll Copilot for the original ITERATION_HEAD. It is expected that Copilot may be reviewing the pre-fix head; use that output as delayed feedback for the same iteration, not as permission to skip it.

• Copilot: posts findings via one of three modes — check both the reviews endpoint and the inline-comments endpoint, treat either signal as completion. Poll every 30s, timeout 10 min when --wait is in effect; otherwise poll briefly and stop with a resume command if it is still pending:

| Mode | pulls//reviews row? | pulls//comments rows? | | --------------------------- | ------------------------ | -------------------------- | | Review with findings | yes (state: COMMENTED) | yes (one per finding) | | Findings without review | no | yes | | Approved with no findings | yes (state: APPROVED) | no |

Mode 2 is real and observed in production. Polling only the reviews endpoint times out in this case while Copilot has already posted findings inline.

```bash # Re-fetch BOTH endpoints — review row OR inline comments at ITERATION_HEAD # are independent signals that Copilot has finished. gh api repos/{owner}/{repo}/pulls//reviews \ > /tmp/pr--reviews.json gh api --paginate repos/{owner}/{repo}/pulls//comments \ > /tmp/pr--comments.json

# Signal 1: top-level Copilot review at ITERATIONHEAD. COPILOTREVIEW=$(jq --arg sha "$ITERATIONHEAD" \ '[.[] | select((.user.login | test("copilot"; "i")) and (.commitid == $sha))] | length' \ /tmp/pr--reviews.json)

# Signal 2: Copilot inline comments at ITERATIONHEAD created since the # iteration started (filters out leftovers from earlier rounds on the # same PR). The commit_id field on review comments matches the head # SHA the comment was posted against, so the watermark is the same as # for reviews. COPILOTINLINE=$(jq --arg sha "$ITERATIONHEAD" --arg t "$ITERATIONSTARTEDAT" \ '[.[] | select((.user.login | test("copilot"; "i")) and (.commitid == $sha) and (.created_at >= $t))] | length' \ /tmp/pr--comments.json)

if [ "$COPILOTREVIEW" -ge 1 ] || [ "$COPILOTINLINE" -ge 1 ]; then # Copilot is done for this iteration — proceed to delayed Copilot parsing. : fi ```

Either signal ≥ 1 → Copilot has finished for this iteration. Do not count reviews or comments of prior commits as completion — those are stale.

Note: 0 inline comments ≠ missing review. A Copilot review on the current commit with state: APPROVED and no inline comments is a clean pass — surface the review body so the user sees it.

If Copilot is still pending after the non---wait poll budget, stop cleanly and report the resume command. Do not start the next iteration while Copilot for the previous ITERATION_HEAD is still pending unless the user explicitly tells you to abandon it. If Copilot times out in --wait mode, log it and proceed with the already-handled fast-pass findings. Note the missing reviewer in the final summary.

---

Phase 2: Parse, categorize, deduplicate

Run this phase twice per iteration:

• Gemini fast pass: parse Gemini findings (inline + summary), dedupe within them, then proceed through fixes/replies.
• Delayed Copilot pass: after the fast-pass push, parse Copilot findings for the original ITERATION_HEAD, dedupe them against the Gemini findings and current code, then fix/reply only what remains.

For Copilot findings already fixed by the Gemini commit, do not edit code again. Reply with the Gemini commit SHA and record the comment id as handled.

Refresh comment fixtures

gh api --paginate repos/{owner}/{repo}/pulls//comments \
  > /tmp/pr--comments.json
gh api --paginate repos/{owner}/{repo}/issues//comments \
  > /tmp/pr--issue-comments.json

Parse Copilot findings

jq '[.[] | select((.user.login | test("copilot"; "i"))
                  and (.in_reply_to_id == null or .in_reply_to_id == 0))
       | {id, path, line, body}]' \
  /tmp/pr--comments.json

For each: classify severity (critical / suggestion / nitpick / question), category (architecture / correctness / security / performance / maintainability / testing), record file path, summarize.

Parse Gemini find

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: loomantix
• Source: loomantix/claude-platform
• License: Apache-2.0
• Homepage: https://github.com/loomantix/claude-platform

Install and usage instructions live in the source repository linked above.