Requesting Code Review
Get an independent verdict on one frozen candidate. Never say a review is running, and never wait on one, until the dispatch action has returned a non-empty receipt (the tool-issued dispatch ID).
When to use
- Before you call an exact candidate complete, and before anything is pushed, published, or merged. A checkpoint you were authorized to commit is not done.
- When the user asks for a review of one exact state.
- Skip here, and go through
finishing-a-branchdirectly, for keep, discard, and PR-only close or reopen: those need its identity and authority checks, not a readiness review. - Skip a plan document;
reviewing-plansreviews it. - Read
references/high-risk-review.mdfirst when the change is a high-risk transformation; it owns the role separation, and one review of an aggregate diff nobody can read does not satisfy it.
Step 1: Verify and freeze
Stop the writers this task started; report any other writer to its owner and keep review pending until it stops.
Read the caller's evidence ledger (add to it, never rewrite it; it sits outside the candidate) for the frozen state and its raw results. Reuse each row whose candidate, bound inputs and environment, check requirements, and evidence freshness still match. Never rerun a matching row.
If there is no ledger, or a row is missing or stale, REQUIRED SUB-SKILL: invoke
verification-before-completionto obtain evidence for this review, then resume here. Keep failures and pending results: they permit review, never readiness.Open
assets/review-candidate.md, the descriptor, after the evidence is bound. Fill every field, and keep its review history across successor candidates. Record a caller only when it has a step awaiting this verdict. A skill whose work ended at this handoff is not a pending return step.A change regenerates
api/client.tsfrom a schema through the project's generator and addsapi/retry.ts, typed by the agent. Both go in the complete inventory. Only the first is generated, so the inventory binds it by identity. The second is human-authored for review; leaving it out as "generated" ships it unreviewed under areadyverdict.Compare its result identity with the state identity the verification evidence carries. If they differ, go back to Step 1.
Step 2: Choose depth and roles
Write the depth into the descriptor:
- Shallow: a self-review. Only when the user, project policy, or the plan's task row assigns it in writing. Never chosen here: the size of the diff grants nothing.
- Standard: one independent breadth reviewer, plus the specialists Step 2.3 selects; at most three roles run at once, and the rest wait for a second round.
- Deep: breadth, specialists, a security role filled from
security-audits' report template and checklists before Step 3.2, and an independent adversarial pass: the breadth prompt again, with Roleadversarialand one named risk to prove. - High-risk transformation: read
references/high-risk-review.mdbefore assigning anyone.
Give every role a stable ID, including each omitted role, whose row fills the descriptor's
Omission disposition.Add a specialist role only when the diff matches its trigger below, then open its prompt template. If no trigger matches, the breadth reviewer runs alone:
assets/silent-failures-reviewer.mdwhen catches, retries, fallbacks, or defaults could swallow a failureassets/type-design-reviewer.mdwhen a type, interface, schema, or shape callers bind to is new or changedassets/test-coverage-reviewer.mdwhen tests should pin the behavior, or behavior moved between covered and uncovered codeassets/comment-accuracy-reviewer.mdwhen comments, docstrings, or prose claim something about the codeassets/equivalence-reviewer.mdwhen the change claims high-risk equivalenceassets/yagni-reviewer.mdwhen enduring surface is new or expanded, or a simplification review is requestedassets/problem-reviewer.mdwhen the change claims to fix a reported problem; it sees the problem and the result, never the diff
Report what another skill owns as a finding with a suggested owner; the caller routes it, and review ends at its report:
- If a trust boundary changed, the suggested owner is
security-audits. That finding blocks readiness at every depth until an independentsecurity clearon this candidate is recorded, unless the Deep security role returned it. Whoever routes the finding requests that audit once, on the first round whose other roles return no blocking finding; until then the finding is carried forward in the review history, not audited per round. Oncesecurity clearon this unchanged candidate is recorded, apply Step 3.7 again; dispatch no new review. - If existing code needs an audit for accidental complexity, the suggested
owner is
complexity-audit. - If the assurance strategy is hollow or needs challenging, the suggested
owner is
verification-strategy.
Record each such finding in the external review ledger. If no caller is recorded, return the finding with the verdict and name its suggested owner as the next skill. If the recorded caller owns that activity, add any brief it supplied to the Step 3.2 dispatch and return the result to its pending step.
- If a trust boundary changed, the suggested owner is
Pick each reviewer's tier with the Model selection section of
dispatching-parallel-agents. Depth sets coverage and independence, not the largest tier for every role.
Step 3: Dispatch and receive
If the depth is Shallow and its written assignment is recorded in the descriptor, run the self-review below and dispatch nothing. If no assignment is recorded, the depth is Standard.
Otherwise open
assets/code-reviewer.mdbefore dispatch, with each selected specialist template. Fill Inputs from the descriptor and raw evidence. Insertassets/review-report.mdbefore sending, in its Report template slot; leave the report fields for the reviewer.Send each filled fenced prompt once, following
dispatching-parallel-agentsStep 2, with the descriptor's deadline as the frozen deadline. If the answer there assigns a self-review, quote it as the Shallow assignment in a successor descriptor and return to Step 3.1.Success means exactly one current report for each role.
Read each returned report, opening its file if only a location was returned. Match Candidate, State read, Review inputs, Role, and the role's allowed Verdict to the frozen request. If a field is missing, unreadable, conflicting, or mismatched, review stays pending. Check the complete inventory and every human-authored change; reject unrelated traversal.
Decide each Declined to judge entry and record it in the ledger, except one that turns on a product, scope, or requirement reading: that goes to its decision owner through
clarifying-intent. An undecided entry keeps review pending.Block readiness while required current verification or role coverage is missing, failed, inconclusive, or conditional, or while a blocking finding or an attempt's effects remain unresolved. Reconcile each advisory finding's recorded decision without adding acceptance criteria.
Record each report's location, its recorded decision, and the tool-issued dispatch ID in the external review ledger.
REQUIRED SUB-SKILL: invoke
receiving-code-reviewwith every report before responding to it, including anot_readythat asks for no edit.Before another round, apply
receiving-code-review's convergence check. If a retry is permitted and the candidate or its bound inputs changed, restart at Step 1 with fresh identities and a fresh receipt. Asecurity clearrecorded on an earlier candidate is rebound to the successor only by the focused independent re-audit of the round's edit thatsecurity-auditsStep 3.4 describes, never by a new audit of the candidate. The Deep security role reruns the same way.REQUIRED — return the verdict through the recorded owner. One other than
readygoes back with its open findings, to the user when no owner is recorded, and never reachesfinishing-a-branch:- If a caller is awaiting this review, return to its pending step; never invoke the caller recursively.
- If the task or plan is owned by
executing-plansorsubagent-driven-development, return there; it owns cadence and plan-end finishing. - If this was a review-only request, an unfinished checkpoint, or an unchanged state with an already settled branch choice, return the verdict.
- If this is a completed standalone implementation or integration
boundary with an unsettled branch choice, invoke
finishing-a-branch, even without a user request for a Git action.
Run no push, PR, merge, keep, or discard here. A ready verdict does not choose an integration action.
Self-review, assigned depth only
- Write
self-reviewed: readyorself-reviewed: not readyagainst the exact candidate hash, after reading the complete change and confirming it does only what was requested. - Account for untracked and generated files, and every affected caller.
- Run a real structural check against that exact candidate.
- If there is a trust-boundary finding without an independent
security clearon this hash, writeself-reviewed: not ready. - On
not ready, do not hand off. Either the assignment did not fit the change: report that to the user, void a no-dispatch answer that assigned it, raise the depth to Standard, and restart at Step 2. Or there is a defect: fix it, then restart at Step 1.
Gotchas
- Rerunning a caller's matching rows looks like rigor, but it verifies one frozen state twice, and a second run that disagrees gets argued away instead of diagnosed.
- A reviewer started in its own worktree or clone reads HEAD without the
uncommitted candidate and still echoes the descriptor's identities.
State readis what it computed itself; a copied or missing one leaves review pending. - A trust-boundary finding without
security clearis not advisory. Filing it as advice to reachreadyships a boundary nobody audited. - Each fix round restarts at Step 1 with a fresh candidate, and a fresh candidate reads as needing a fresh audit: one run audited every round of every task. The audit runs once at convergence; a fix round after it gets a focused re-audit of its edit, not a new audit.
Common mistakes
- Treating checks, workspace size, urgency, or completion pressure as an independent reviewer or as permission to downgrade.
- Inventing delegation authority, or treating an action as disclosure consent.
- Asking a reviewer to mutate the frozen candidate; destructive challenge runs only in a reviewer-owned copy or against retained evidence.
- Filling high-risk roles that must stay separate with the same party, without a direct recorded exception.