Code Review That Terminates: A Skill for Finite Agent Rounds

Where this fits

You’re an agent that just finished a feature branch. You run a review, get a list of issues, fix them, and run review again — but the second round returns a different set of problems, and a third round finds yet another batch. The diff is the same; the review isn’t. That’s the failure mode code-review kills. Instead of an open-ended hunt, it enumerates a closed list of items from two source documents — the repo’s documented standards and the originating issue’s spec — then returns a verdict per item. Every round terminates, and you can tell whether the fix actually closed the loop.

Why agents benefit

• Bounded rounds — Each axis returns a verdict per enumerated item, so the agent knows when the review is complete. No “more findings” spiral.
• Parallel sub-agents — Standards and Spec reviews run concurrently, then report side by side, cutting review latency in half.
• Fixed-point semantics — Diff scope is pinned to a commit, branch, tag, PR, or merge-base, so “review since X” is reproducible across runs.
• Fix verification — After changes, re-running the same skill compares against the same enumerated list, making “did we address that?” a yes/no check.
• Repo-aware standards — It reads the repo’s own documented rules (e.g., CONTRIBUTING, ADRs, style guides) rather than applying generic best practices.

Practical scenarios

Review a PR before merge

An agent watches for a new PR, runs code-review with the PR head as the diff base, and posts both axis verdicts as a comment. The human sees exactly which standards items failed and which spec items are unmet — no noise.

Review working-tree changes after a refactor

You’ve been editing locally and ask “review since main.” The skill computes the merge-base, enumerates the standards list (e.g., “no TODO comments,” “error wrapping follows xerrors pattern”), and reports per-item pass/fail. You fix the two failures and re-run — now all items pass.

Verify a bug fix against its issue

Your agent fixed issue #42. Run code-review with the issue as spec source. The Spec axis returns “handles empty input: PASS, retries on 503: FAIL, logs correlation ID: PASS.” You fix the retry logic, re-run, and the FAIL becomes PASS. Done.

Add it to your agent workflow

Install via npx (requires Node 18+):

npx skills add ConnorGriffin/skills --skill code-review

Then invoke it in your agent prompt:

Run code-review on the current branch against main. Report both axes side by side.

The skill will detect the diff base, enumerate items from the repo’s standards docs and the linked issue, and return a structured verdict list.

Compare before adopting

Before you wire this in, compare against alternatives like pr-review or generic “find bugs” agents. Check: does it produce a finite list or an open-ended set? Does it read your repo’s own rules or a generic checklist? How fresh is the skill (last commit, open issues)? Does it fit your workflow — e.g., can you pass a custom spec source (issue vs. plan)? The OpenAgentSkill listing shows usage stats and version history.

Why it is worth tracking

This skill solves a real agent-loop problem — review termination — with a design that’s easy to reason about. It’s young (20 stars) but the pattern is sound and the author is active. Watch for adoption signals: more stars, issues resolved, and whether it gains support for custom spec sources (e.g., markdown plans). If you’ve hit the “reviews never converge” wall, this is worth a trial in a sandbox branch today.