Review helpers: cross-doc-review and cross-code-review review an artifact with two independent reviewer agents which check each other and adjudicate any single-reviewer finding before it is adopted; comments-cleanup strips comments that tell the reader nothing beyond what the code itself says out of a code change and rewrites the survivors to state what the code does

Install

/plugin install review-tools@powdream-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add powdream/claude-plugins.

Contents

Discovered from source

Skills 3

Comments Cleanup

Strips comments that tell the reader nothing beyond what the code itself says, and rewrites the survivors into one line that states what the code does.

1. Pick the scope — ask first

An explicit path argument wins. Use those paths and skip the discovery below.

Otherwise resolve the base first — origin/main may not exist, and a branch stacked on another PR has to be scoped against its own base, not the ancestor PR's files:

gh pr view --json baseRefName -q .baseRefName                   # this PR's base branch
gh repo view --json defaultBranchRef -q .defaultBranchRef.name  # fallback: default branch
git symbolic-ref --short refs/remotes/origin/HEAD               # offline fallback

<base> is that branch name prefixed with origin/ (the third command already prints it that way). If none of them answer, scope from git diff --name-only HEAD alone, or ask.

The changed files are the union of:

git diff --name-only HEAD            # staged + unstaged
git diff --name-only <base>...HEAD   # committed on this branch

Untracked files are not in that union. List them separately — the command also picks up scratch files and un-ignored build output, so they are never folded in silently:

git ls-files --others --exclude-standard    # new files, not yet tracked

If it prints nothing, say nothing about it.

Then use AskUserQuestion to pick one. When the untracked list is non-empty, name those paths in the question text, so the choice is made with them in view:

  • Changed lines only — comments on lines this change added or modified.
  • Whole changed files — every comment in those files.
  • Whole changed files + the untracked paths listed — offer this option only when that list is non-empty.

An untracked file enters the working set only through that third option. Never widen past what the user picked, and never touch a file the change did not already modify, unless a path argument named it. The one exception: a rename or an extraction approved in §2 may follow its references into files outside this scope.

2. Apply the meaning test

For every comment in scope, answer one question:

Does this comment tell the reader something the code itself does not?

Meaning beyond the code is one of:

  • why the code is this way
  • a rule that lives outside this code — a server, the app the code was ported from, an external tool
  • domain meaning
  • a trap

Context the code does not carry is a reason to keep the comment, not a reason to delete it. Write the answer down before deciding.

Always delete, whatever else is true:

  1. Restates the code — what a name, a type, the next line, or the control flow already says.
  2. Private symbols — notation a reader of this code cannot resolve. §3 names what counts and what is allowed.

One way to find a trap: ask what specific wrong change somebody would make with the comment gone. That question is auxiliary — a comment can carry meaning beyond the code with no such change in view — and its answer is never the comment's text.

Can the code say it instead?

Before keeping a comment that carries meaning beyond the code, check whether the code itself could carry that meaning:

KindSignalExample
Renamethe comment supplies what an unclear name should sayint d = …; // days since the campaign started → daysSinceCampaignStart
Extractthe comment names a magic value or an expressionif (status == 3) { // withdrawn → CampaignStatus.withdrawn
Structural refactorsection comments split a long function, or the comment exists because the code is tangled// --- validate --- … // --- persist --- → validate(); persist();
Nonewhy, an outside rule, a bug workaroundkeep the comment, rewritten to the shape in §4

The skill steers the user toward the refactor with AskUserQuestion:

  • Collect every rename, extract, and refactor candidate after the scan, then ask one question per candidate — at most 4 questions per call, more candidates need more calls.
  • The first option is the refactor itself, with the proposed name or change in the label and (Recommended) appended; the second option keeps the comment.
  • The question text states that the comment is deleted once the refactor is applied, how many files the change touches, and "public API change" when the symbol is public or exported.

Applying the approval:

  • A rename or an extraction applies at once: update every reference, then run the repository's build, lint, and tests.
  • A structural refactor runs as a separate step after the comment pass, reported on its own; the comment stays until then.

A doc comment on a public or exported declaration gets a second question:

Beyond its name and signature, what does this thing do?

That answer is the doc comment's first sentence. Who calls it, when, and why it exists are not answers; the call sites carry those. The answer is more than the name when it states the input, the output, or a guarantee: Exporter renders a day's ledger rows as a CSV file names both ends, Exporter exports is the name. When the answer is only the name, the comment goes. When the repository's linter requires a doc comment on every exported identifier (Go revive exported, Dart public_member_api_docs), the one-sentence name form stays.

3. Delete these

Ordered by how often they show up:

  1. Restates the code, or restates the line directly next to it.
  2. Private symbols — plan task numbers, decision ids, internal abbreviations, and a file or symbol name from another repository (for example the source app the code was ported from). Allowed: the ticket key in a TODO that names its removal condition, and the ticket reference of a bug the code works around. A file path inside this repository is code the reader can open, not a private symbol.
  3. Tutorial-style rationale — two sentences or more of explanation.
  4. Justification — // Needed: …, // No lock: …, // We chose X because …. The comment defends a choice. When the code shows the consequence (WithTimeout(ctx, deployTimeout) sits on the next line), the comment goes. When the consequence names something outside this file — a lock held elsewhere, a default being overridden, a service's behaviour — the comment becomes that consequence, in the shape in §4.
  5. Usage narration — who calls it, when, from where: is used by the deploy workflow when a merge to main happens. Call sites show it.
  6. Change-history commentary — // removed the old logic, // changed from X, // was: .... Git already knows.
  7. Section-divider decoration — // ===== helpers =====.
  8. Obvious type or name annotations, and commented-out code.
  9. Anything already written in README, AGENTS.md, CLAUDE.md, or a spec.

4. Keep these

Never delete — a tool reads these, not a person. The meaning test does not apply; deleting them breaks the build:

  • Compiler and toolchain directives — //go:build linux, # noqa: E501, // eslint-disable-next-line, # type: ignore, @ts-expect-error, coverage pragmas.
  • Codegen headers — // Code generated by protoc-gen-go. DO NOT EDIT.
  • License and SPDX headers.
  • Machine-read markers such as [start] / [end], and any other comment a tool parses.

Run the repo's build or lint after editing. A directive deleted by mistake shows up there and nowhere else — the counts-only report hides it.

Keep by judgement:

  • Temporary code whose removal condition names a precise trigger. "Remove someday" does not qualify; "remove once the ledger migration in INF-1234 lands" does.
  • A comment that names the ticket for a bug it works around (internal tracker or upstream issue).
  • The reason for genuinely non-obvious behaviour — one line.
  • One line of reason per exception, or per false entry in a config list.
  • A pointer to the file this code mirrors, when both files live in this repository and a reader cannot infer the mapping locally.

The shape of a surviving comment

A surviving comment is one line that states what the code does or guarantees at that point. Its subject is the code, and its verb is affirmative.

  • An inline comment names the behaviour: what runs, what is returned, what is guaranteed, what is skipped and what happens instead.
  • A doc comment's first sentence names the declaration and what it does, in the language's doc convention (Go: Deployer registers …; Dart: /// Computes …). Constraints the signature does not carry follow, one line each.
  • A comment on a setting that overrides a default states what the setting makes happen.
  • The line is the consequence and nothing after it. A tail that begins with because, so that, to avoid, otherwise, would, or ; the X needs is the justification coming back. Cut the tail; when the code shows what is left, the comment goes.
BeforeAfter
// Deployer is used by the deploy workflow when a merge to main happens, because the workflow needs a single entry point to push a task definition and wait for the service to become stable.// Deployer registers a task definition and waits for the ECS service to stabilize.
// No lock: taking the deploy lock here would block manual deploys from the console.// UpdateService runs outside the deploy lock; console deploys proceed concurrently.
// Needed: without the timeout a stuck service blocks the runner forever.deleted — WithTimeout(ctx, deployTimeout) on the next line shows it
# No lock: locking would block manual applies# Comparison-only plan: output feeds the diff check, never applied.
/// Used by CheckoutScreen when a coupon is applied to get the new total./// Computes the discounted total for a cart with a coupon applied.
# chunked to avoid OOMdeleted — chunks(rows, BATCH) on the same line shows the batching
"""Builds the CSV. We don't stream because the admin button needs the whole file.""""""Builds the CSV for day and returns the whole file in memory."""

A surviving comment still gets compressed: at two sentences or more, cut it to one line.

5. Language

Match the language of the file's existing comments. Default to English when the file has no established one. Never mix languages inside one comment — # 등록に必要な権限 is a defect, not a style choice.

6. Report

One line per file: comment-line counts, the number rewritten, and the number renamed or refactored:

internal/broker/deploy.go       24 → 11  (3 rewritten, 1 renamed, 1 refactored)
.github/workflows/deploy.yml     7 → 2

Do not reprint the deleted comments. That output is the verbosity this skill exists to remove.

Cross-code review (two agents, cross-checked)

Review a code change with two independent strong reviewers and only accept a finding after it survives an adversarial cross-check. A single reviewer misses real bugs (blind spots) and raises confident false positives (overreach). Two strong reviewers of different provenance cover more, and making each one try to refute the other's solo findings kills plausible-but-wrong claims before they reach the user.

Roster (default — models are swappable, the roles are not)

  • Reviewer A — codex, run through the codex CLI. A different vendor/engine, strong at reading a repository directly.
  • Reviewer B — opus, run through the Agent tool with model: "opus".

Both reviewers are strong, so verification is symmetric: a codex-only finding is verified by opus, and an opus-only finding is verified by codex. There is no lighter third model — with two strong reviewers, the peer is the right judge. (This differs from cross-doc-review, where the weaker reviewer's solo findings go to a stronger third model. Keep the shape you need: two first-pass reviewers, and each solo finding adjudicated by an independent reviewer of at least equal strength.)

Inputs

  1. Change under review: a diff scope the reviewers can reconstruct — git diff <base>...<head>, a PR number, a commit range, or an explicit list of changed files. Prefer a diff over "the whole repo" so review stays focused.
  2. Criteria (the review lens): default to references/code-review-criteria.md. If the project has its own review checklist or conventions doc, use it (and hand it to both reviewers) — the orchestration below is unchanged.

Confirm the diff scope and criteria if either is ambiguous. Otherwise proceed.

Workflow

1. Run both reviewers in parallel (same turn, same change, same criteria)

Launch A and B in the same turn so neither sees the other's output. Give both the identical diff scope and criteria, and ask for the identical shape: findings as a list, each with file:line, a severity, a concrete failure scenario (inputs/state → wrong result), and a suggested fix.

Reviewer A (codex). codex needs to read the repository and reach its model, so run it from the repo root with the sandbox disabled (on the Bash tool, set dangerouslyDisableSandbox: true). Have codex write its result to a file and read that file — its stdout carries hook/log noise, so a file it wrote is far cleaner than scraping stdout. Redirect stdin from /dev/null or codex hangs.

(cd <REPO_ROOT> && codex exec --dangerously-bypass-approvals-and-sandbox \
  "Review the change (<DIFF_SCOPE>, e.g. git diff <base>...<head>) against the
   criteria below. For each finding give file:line, severity, a concrete failure
   scenario (inputs/state -> wrong output/crash), and a fix. You may run git and
   read files. WRITE your final result to <ABS_OUT_PATH> and nothing else to
   stdout.
   Criteria:
   <criteria text>" < /dev/null)

Then Read <ABS_OUT_PATH>.

Reviewer B (opus). Spawn an Agent with model: "opus". Give it the diff scope and criteria, tell it to inspect the change (it can use git / Read / Grep), return findings in the same shape as its final message, and not edit code (read-only review). Its final message is the result.

2. Classify every finding

Match findings by the underlying defect, not by wording, and sort into:

  • both — raised by codex and opus.
  • codex-only.
  • opus-only.

3. Adversarially verify the single-reviewer findings

  • both → confirmed. Adopt.
  • codex-only → send to opus to verify.
  • opus-only → send to codex to verify.

Give the verifier only the solo findings plus the change, and ask it to try to refute each one: does the failure actually reproduce, is the code path reachable, does the fix change behavior? Return [confirmed / plausible / refuted] with a one- or two-sentence reason. Default to refuted when the verifier cannot construct the failure — a finding that cannot be made to fail is not worth the user's time.

Adopt a solo finding only if it comes back confirmed or plausible. Record refuted findings with the reason — a killed false positive is a result too.

4. Consolidate and report

Present a single verdict, most-severe first:

Confirmed (both) — adopted:
- <file:line> <defect> — <failure scenario>

Single-reviewer, verified:
| source | finding | verifier verdict | outcome |
|---|---|---|---|
| codex | <file:line> …  | opus: refuted   | not adopted (reason) |
| opus  | <file:line> …  | codex: confirmed| adopted |

Then either apply the adopted fixes or hand the list back, per what the user asked. If you apply fixes, say which findings you rejected and why, so the user can overrule.

Notes

  • Cost. This spends two models (codex, opus) plus your own passes and the verification round. Worth it for a change that matters; for a quick glance a single reviewer is enough — say so rather than spending the full panel.
  • Independence. Never show one reviewer the other's output before step 3. Their disagreement is the signal; contaminating them collapses it.
  • Adversarial by default. For code, verification means trying to break the claim, not re-stating it. A finding that survives a genuine refutation attempt is worth acting on; one that does not, is not.
  • The verifier is not an editor. Verifiers judge; they do not rewrite code. You own the edits after adoption.

Cross-document review (two agents, cross-checked)

Review a document with two independent reviewers and only accept a finding after it survives cross-checking. One reviewer alone is easy to over-trust: it has blind spots (misses real problems) and it overreaches (flags non-problems with confident prose). Two reviewers of different provenance cover more, and routing each single-reviewer finding to a different verifier means a lone claim is judged by a fresh perspective instead of being rubber-stamped by an equally fallible peer.

Roster (default — models are swappable, the roles are not)

  • Reviewer A — codex, run through the codex CLI. A different vendor/engine from the Claude side, so its blind spots differ.
  • Reviewer B — fable, run through the Agent tool with model: "fable".
  • Adjudicator — opus, run through the Agent tool with model: "opus". Used only to judge codex's solo findings. It does not do a first-pass review.

The asymmetry is deliberate: codex's solo findings go to opus, not to fable. codex is the outside engine and tends to be the most aggressive reviewer, so its un-corroborated claims are adjudicated by the strongest independent judge rather than by the lighter peer. fable's solo findings go to codex (the ordinary mutual cross-check). If you swap models, keep this shape: two first-pass reviewers, and a stronger third model that adjudicates the CLI reviewer's solo findings.

Inputs

  1. Target: the path to the document to review.
  2. Criteria (the review lens): what to check for. Default to references/document-quality-criteria.md (a reader-perspective checklist for prose quality). If the user gives their own criteria, or the artifact is not prose (code, config, a design), use theirs instead — the orchestration below is unchanged.

Confirm the target and criteria with the user if either is ambiguous. Otherwise proceed.

Workflow

1. Run both reviewers in parallel (same turn, same criteria)

Launch A and B in the same turn so they finish together and neither sees the other's output. Give both the identical criteria and ask for the identical output shape: a per-criterion [pass / issue] verdict with evidence and a concrete fix, then a severity-ordered findings list where each finding is tagged F1, F2, …

Reviewer A (codex). codex needs network/model access, so run it with the sandbox disabled (on the Bash tool, set dangerouslyDisableSandbox: true). Have codex write its result to a file and then read that file — codex's stdout is full of hook/log noise, so parsing a file it wrote is far cleaner than scraping stdout. Redirect stdin from /dev/null or codex hangs waiting for input.

codex exec --dangerously-bypass-approvals-and-sandbox \
  "Read the document at <ABS_PATH> and review it from a reader / document-quality
   perspective (NOT correctness of the underlying subject). For each criterion
   below, give [pass/issue] + evidence (section, quote) + a concrete fix.
   End with a severity-ordered list, each item tagged F1, F2, ...
   WRITE your final result to <ABS_OUT_PATH> and nothing else to stdout.
   Criteria:
   <criteria text>" < /dev/null

Then Read <ABS_OUT_PATH>.

Reviewer B (fable). Spawn an Agent with model: "fable". Tell it to Read the document, apply the same criteria, return the same shape as its final message, and not edit the file (read-only review). Its final message is the result.

2. Classify every finding

Match findings by the underlying issue, not by wording, and sort into:

  • both — raised by codex and fable.
  • codex-only.
  • fable-only.

3. Cross-verify the single-reviewer findings

  • both → confirmed. Adopt.
  • fable-only → send to codex for an independent verdict.
  • codex-only → send to opus (Agent, model: "opus"), not to fable.

Give each verifier only the solo findings plus the document, and ask for an independent [valid / partial / reject] per finding with a one- or two-sentence reason and a concrete fix when valid. Tell it not to take sides. When a verdict depends on a house rule (e.g. a template's section order), give the verifier that reference so it can judge against the standard, not its taste.

Adopt a solo finding only if its verifier returns valid or partial. Record rejects with the verifier's reason — a rejected finding is a result too.

4. Consolidate and report

Present a single verdict, most-impactful first:

Confirmed (both) — adopted:
- <finding> …

Single-reviewer, cross-verified:
| source | finding | verifier verdict | outcome |
|---|---|---|---|
| fable  | …        | codex: partial   | adopted (…) |
| codex  | …        | opus: reject     | not adopted (reason) |

Then either apply the adopted fixes or hand the list back, per what the user asked for. If you apply fixes, say which findings you rejected and why, so the user can overrule.

Notes

  • Cost. This spends three models (codex, fable, opus) plus your own passes. It is worth it for a document that matters; for a quick sanity read, a single reviewer is enough — say so rather than spending the full panel.
  • Independence. Never show one reviewer another's output before step 3. The value is in their disagreement; contaminating them collapses it.
  • The verifier is not an editor. Verifiers judge; they do not rewrite the file. You own the edits after adoption.

Sponsors

Details

Marketplace
powdream/claude-plugins
Source
plugins/review-tools
Category
Community

More from powdream/claude-plugins

All 8