pappcorn/universe / .claude/skills/review-loop
review-loop
UnverifiedDrive an open pull request through this repo's automated review gate until it is green and ready for human approval. Waits for the `claude-review` check (workflow "Claude Code Review") and CI to settle, reads the posted `## Findings` review comment, then fixes every blocking π΄ Important finding (edit + conventional commit + push, which deterministically re-runs the gate) or disputes it by replying `@claude` on the PR. Loops until the check passes or escalates a contested finding to the maintainers. When green, applies the `ready-to-merge` label β which in this repo only pings the human reviewers for approval; it never merges anything. Use when asked to "run the review loop", "wait for the review", "get this PR to green", "address the review findings", or "poll the PR until it passes".
/review-loop β drive a PR to a green review
Run the review loop on a pull request in pappcorn/universe: wait for the
automated gate, fix or dispute every blocking finding, and loop until the PR is
green β then hand it to the human reviewers.
Arguments ($ARGUMENTS, all optional, any order):
- A bare PR number or URL β the PR to run on. Default: the PR for the current branch.
--max Nβ max fix/dispute iterations before escalating. Default:3.--dry-runβ poll and report the findings, but do not fix, dispute, or push.
The gate contract (this repo)
- Check:
claude-review, from the workflow "Claude Code Review" (.github/workflows/claude-code-review.yml). It runs on every PRopened/synchronizeevent, posts a review comment, and fails the check unless the review verdict is PASS. - Findings: the review is a PR comment containing a
## Findingssection. Always read the latest## Findingscomment posted after the current head commit's run started β an older comment describes an older diff. - Severities:
- π΄ Important β blocks merge. The check fails while any exists.
- π‘ Nit β does not block. Fix if cheap, otherwise leave a short comment.
- π£ Pre-existing β informational, never blocks.
- Determinism: the gate grades the pushed diff. Same diff β same verdict.
The only way to flip a failing check is to change the code and push. A
comment triggers a conversation (
@claudereplies via.github/workflows/claude.yml), never a re-grade.
Step 0 β Resolve the PR
- If
$ARGUMENTShas a number/URL, use it; elsegh pr viewon the current branch. No PR β stop and say so (this skill does not open PRs). - Confirm the PR is
OPEN. Record its number, base, and head branch.
Step 1 β Make the branch current and the diff pushed
The gate grades the pushed diff against the base.
git fetch origin <base>and checkgit log --oneline HEAD..origin/<base>. If the base moved ahead, merge it in (git merge origin/<base>orgh pr update-branch). Trivial conflicts only β anything non-obvious stops the loop and goes to a human.- Push any unpushed commits with a plain
git push. Never force-push. - Uncommitted changes in the tree β stop and tell the user; the loop grades committed, pushed code.
Step 2 β Wait for the gate and CI to settle
gh pr checks <PR> --watch --interval 30 --json name,state,bucket,workflow,link
--watch blocks until every check completes and exits non-zero if any failed β
that exit code is a signal, not an error. Capture the JSON either way. If the
claude-review check never appears after CI completes, surface that instead of
treating it as green.
Step 3 β Read the verdict and the findings
- Gate: the
claude-reviewcheck. Green iff its bucket ispass. - CI: the
CIworkflow check (nx affected -t lint test build). For a red CI check, pull the failing detail:gh run view <run-id> --log-failed. - Findings: fetch the newest qualifying review comment:
gh api "repos/pappcorn/universe/issues/<PR>/comments" --paginate \
--jq '[.[] | select(.body | contains("## Findings"))] | last | .body'
Verify it postdates the current head commit's review run (compare created_at
against the run's start time from gh run list). Split findings by severity.
Red without a verdict β infrastructure failures
claude-review can fail before any review runs. If the check is red and no
## Findings comment postdates the run, read the failure log
(gh run view <run-id> --log-failed) and classify instead of looping:
- The PR modifies
claude-code-review.ymlitself. The action's app-token exchange requires the workflow file on the PR head to be byte-identical to the one on the default branch, and otherwise fails with401 Workflow validation failed. That is the action's tamper guard, not a review verdict β no push can turn the check green while the workflow change is part of the PR. Post the classification as a PR comment so the human reviewers know the red is expected, then stop; the check heals on the first PR after the workflow change merges. - Any other pre-review error (bad or expired credentials, a retired model id, runner issues): there is no code finding to fix. Surface the relevant log excerpt on the PR and escalate (Step 6) β never retry-loop hoping for a different outcome, and never weaken the workflow to get past it.
If --dry-run: report verdict + findings and stop here.
Step 4 β Fix or dispute each π΄ (and red CI)
Default to fix β the reviewer is usually right, and only a code change can flip the gate.
Fix: make the minimal edit for that finding (no drive-by refactors), commit
with a conventional-commit message scoped like the repo history
(fix(gmail-mcp): β¦, chore(ci): β¦), and let Step 5 push. Fix red CI the same
way (lint rule, failing test, build error).
Dispute (when the finding is genuinely wrong): reply on the PR tagging the reviewer so the exchange is on the record:
gh pr comment <PR> --body "@claude Re: <finding>. <concrete counter-argument with file:line evidence>. Do you still consider this blocking?"
Know the limit: a comment gets a reply, not a re-grade. If the dispute ends with no code change, that is an escalation (Step 6), never a workaround.
π‘ Nits: fix them when cheap; otherwise leave a one-line comment saying why not. π£ Pre-existing: acknowledge if useful; they never block and out-of-scope fixes belong in their own PR.
Step 5 β Re-push and re-grade
If Step 4 produced commits, git push (plain form). That synchronize event
re-runs the gate on the new diff. Increment the iteration counter and go back
to Step 2 β until green or --max is hit. If Step 4 produced no commits
(pure dispute), go straight to Step 6.
Step 6 β Terminate
Green (success)
When claude-review and CI both pass:
- Post a short summary comment: verdict, iterations, what was fixed.
- Apply the label:
gh pr edit <PR> --add-label ready-to-merge
In this repo the ready-to-merge label is an authorization: it triggers
.github/workflows/cris-approve.yml, which re-checks the objective gate and β
when the PR's author is a human code owner of everything it touches β approves
as Cris and arms GitHub's native auto-merge. When the author is Cris or an
outside contributor, or the PR touches a governance carve-out
(cris-approve.yml, CODEOWNERS), a human code owner (@ni500, @lcaloguerea)
must approve β branch protection enforces it. The full decision table lives in
CONTRIBUTING.md ("Who can approve").
Escalate
When --max iterations are spent with a π΄ remaining, or a π΄ is contested
and will not be changed in code: post a PR comment tagging @ni500
@lcaloguerea with the unresolved finding (file:line, one line each), a link
to any @claude dispute thread, and a recommendation. Then stop β the
maintainers break the tie.
Whose name the writes go out in
When this loop runs as the agent maintainer, its comments and pushes go out as
the agent's GitHub App (cris-de-pappcorn[bot]), with a short-lived token the
operator's machine mints for this repo. Two things to get right:
-
Fail closed.
ghsilently ignores an emptyGH_TOKENand falls back to whatever account is logged in locally, so a failed mint would post as the human without a word. Make a failed mint produce a token that cannot work:t="$(<mint-command>)"; GH_TOKEN="${t:-unresolved}" gh pr comment <PR> --body "β¦"The fallback keys on the captured value being empty, not on the exit code: a mint that fails but exits 0 (a pipeline ending in
jq, say) still prints nothing. If the mint is a pipeline, run it underset -o pipefailtoo. A401then stops the loop, which is the point. Never print the token. -
The label is not the agent's to apply.
cris-approve.ymlonly takesready-to-mergefrom a human code owner, and it counts the App as Cris. Apply the label from the human maintainer's ownghlogin (noGH_TOKEN), or hand that one step to them.
Hard rules
- Never fake green. No editing the workflow, weakening the check, or merging around it. The only paths to green are a code fix or a maintainer's ruling.
- Never force-push. Plain
git pushonly. - Never merge.
gh pr mergeis out of scope in every form. Merging is the human reviewers' call after approval. - Only π΄ blocks. Don't chase π‘/π£ to green, and don't ignore them silently either β a one-line disposition is enough.
- A comment doesn't re-grade. Only a push re-runs the gate; build the loop around that.
- Scope discipline. Fix the finding, not adjacent code.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why β repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" β or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself β your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |