Skip to content

pappcorn/universe / .claude/skills/review-loop

review-loop

Unverified

Drive 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 PR opened / synchronize event, posts a review comment, and fails the check unless the review verdict is PASS.
  • Findings: the review is a PR comment containing a ## Findings section. Always read the latest ## Findings comment 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 (@claude replies via .github/workflows/claude.yml), never a re-grade.

Step 0 β€” Resolve the PR

  • If $ARGUMENTS has a number/URL, use it; else gh pr view on 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.

  1. git fetch origin <base> and check git log --oneline HEAD..origin/<base>. If the base moved ahead, merge it in (git merge origin/<base> or gh pr update-branch). Trivial conflicts only β€” anything non-obvious stops the loop and goes to a human.
  2. Push any unpushed commits with a plain git push. Never force-push.
  3. 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-review check. Green iff its bucket is pass.
  • CI: the CI workflow 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.yml itself. 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 with 401 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:

  1. Post a short summary comment: verdict, iterations, what was fixed.
  2. 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. gh silently ignores an empty GH_TOKEN and 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 under set -o pipefail too. A 401 then stops the loop, which is the point. Never print the token.

  • The label is not the agent's to apply. cris-approve.yml only takes ready-to-merge from a human code owner, and it counts the App as Cris. Apply the label from the human maintainer's own gh login (no GH_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 push only.
  • Never merge. gh pr merge is 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.
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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 319kUpdated Claude CodeCodexVerifiedInstall