Review Code

Review Code

Review code against type-specific criteria. Runs internal reviews and $peer-review in parallel by default. Returns combined structured findings.

Types: correctness, security, api-usage, consistency, simplicity, coverage

With a type argument, runs a single-concern internal review plus the peer review. With no type argument, runs all six internal reviews plus the peer review.

Step 1: Determine the Scope

Determine what to review:

• If a specific diff command was provided (e.g., git diff --cached, git diff origin/main...HEAD), use that.
• If a file list or directory was provided, review those files directly (read the full files, not a diff).
• If neither was provided, default to diffing against the repository's default branch (detect via gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'). If there are no changes against the default branch, stop and state that there is nothing to review.

State the resolved file list before continuing: add --name-only to a diff command, or list the files for a file or directory scope. When the scope is a staged diff, also state how many further files git diff HEAD --name-only reports, so a scope narrower than intended stays visible before fanning out.

Step 2: Run Reviews in Parallel

Each active type maps to a criteria reference file:

• Correctness — references/correctness-review.md
• Security — references/security-review.md
• API usage — references/api-usage-review.md
• Consistency — references/consistency-review.md
• Simplicity — references/simplicity-review.md
• Coverage — references/coverage-review.md

Full review activates all six types; a single-concern argument activates one. Skip peer review when instructed (e.g., "without peer review", "no peer", "internal only").

Before dispatching, read the project's test configuration and CI workflow to identify any test tier that resets a shared external resource between tests, such as a database, a fixed port, or a cache. Such tiers have no cross-process interlock, so branches running them concurrently wipe each other's state and return failures indistinguishable from defects in the change. Name any such tier to every branch as off-limits when the review does not depend on running it. When the change under review is what that tier exists to exercise, so that judging it at all requires running the tier, direct each branch instead to provision its own isolated instance of the resource, prepare it through the project's own setup path, run against it, and tear it down afterward. One shared instance carrying an instruction to run a single branch at a time is not sufficient, since nothing enforces that across branches. When a branch's own instance cannot be provisioned, the tier is left unrun and reported as such.

Direct every branch that runs a test suite to redirect the runner's output to a file under $TMPDIR and read the file. Piping a runner to head, tail, or another command that closes the stream early returns while the runner is still going, so a branch that believes its run finished leaves one live to overlap the next branch's.

When the scope contains a guard whose safety rests on an assumption stated in the conversation, in a plan file, or in a code comment, give every branch that assumption as the claim to refute rather than as background.

When the scope contains content that a build or render transform rewrites before it ships — markup compiled to components, template expansion, code generation, translation extraction — build the project before dispatching, in an isolated git worktree under $TMPDIR when the build writes to tracked files or reaches the shared install through a package-manager wrapper, and name the emitted files as part of the scope every branch receives, so each type judges the emitted artifact rather than the source. Refer to that worktree by absolute path in every command and join chained steps with &&, so a failed step cannot leave the rest running in the shared checkout.

Confine each branch prompt to what to review, plus the conventions and factual properties that bear on it. A statement that tells a branch what verdict to reach about a property of the existing code binds it to accept the very property the review exists to assess.

When this session edited an instruction file or a file one imports, name it in every branch prompt and direct the branch to read it from disk before judging anything against it: the copy loaded into a branch's context can predate the edit.

When a list of already-adjudicated findings was supplied (one line each: the finding, its verdict, and the recorded reason), include it in every branch prompt, internal and peer, labeled as decisions already reached on proposed changes rather than as established properties of the code. Direct each branch to treat a finding as listed when it matches one on both location and substance, to raise such a finding again only on evidence its recorded reason does not already account for, and to judge any other finding at the same location on its own merits.

Run the review branches independently. Launch them with spawn_agent / wait_agent using inherited model defaults, issuing every call in one batch. Do not issue one and await its result before issuing the rest. For full review that is six internal branches plus one peer branch; for single-concern it is one internal branch plus one peer branch. Every branch prompt must direct it to treat the shared working tree and its git index as read-only and to assess findings by reading and reasoning. HEAD stays where it is: read other refs with git show <ref>:<path> rather than git checkout or git switch. For a check that requires mutating code, the branch works in an isolated git worktree created under $TMPDIR and discarded afterward. In a repository with no commit yet, where a worktree has nothing to check out, an export of the index stands in for one: the branch runs git checkout-index -a --prefix=<dir>/ from the repository's top level, with <dir> under $TMPDIR, then git init and git add -A -f in that directory, so git diff there shows a mutation. Every rule here that names the worktree applies to that directory, and the branch verifies afterward that the directory is gone. Refer to that worktree by absolute path in every command and join chained steps with &&, so a failed step cannot leave the rest running in the shared checkout. Run teardown and verification as their own commands. Give that worktree its own dependency install rather than reaching the shared tree's install by any route: removing a worktree deletes through symlinks, and a redirected suite writes into the shared install. When its own install is not possible, the check is left unrun and reported as such. A check that runs in the shared checkout invokes an already-installed runner directly wherever a package-manager wrapper would front it, since such a wrapper reads as read-only while reconciling the shared install before it runs. Confine dependency installs and reconciliation to an isolated worktree. Every test runner the branch starts, in a worktree or in the shared checkout, runs in its own process group under a timeout enforced from outside the runner. Before teardown, the branch stops the process group of every runner it started, since stopping a runner can leave the processes it spawned alive. Afterward the branch verifies that git worktree list no longer shows the worktree, that git status --short shows what it showed at the start, and that HEAD is still on the branch it started on. It also confirms that no process from those groups, and none whose command line names the worktree path, if any, is still running, and reports by PID any process it could not stop. When it cannot list processes, it reports that check as unrun and names those process groups and the worktree path, if any. After any check, in a worktree or in the shared checkout, it verifies that the shared tree's dependency directory still resolves (a destroyed install leaves git status unchanged, since it is gitignored). Damage the branch cannot repair is reported with the exact repair command in place of findings.