code-review

Code review

Coordinate a compact reviewer or focused specialists to review an existing change set as read-only input and produce one evidence-backed report.

Orchestrator instructions

Spawn every reviewer fresh with fork_turns="none"; never reuse one for validation or resolution.
Ignore staged versus unstaged status. Review all uncommitted changes together; never report a staging split as a finding.
Keep repository files read-only. Use collaboration messages for review state. Repository task-completion verification instructions apply to implementation work, not review.
Record validation results available when review starts as Available validation evidence, including their exact target and actual status when known; use Unavailable when none exist. Treat this evidence as context, not proof that the change is correct.
Build each reviewer launch envelope from the shared review context, its assignment packet, feature context instructions and brief reference, reviewer instructions, applicable mode instructions, assigned review roles, and applicable guidance collected in Step 1. Include subagent model selection when the recipient can delegate. Keep review-wide routing and lifecycle metadata outside assignment packets so packets describe only review responsibility; do not ask reviewers to rediscover scope.
Schedule or batch specialists so each specialist can spawn its required children without exceeding the available agent limit.
Report checked scope and actual findings. Mark review incomplete when missing context or expertise blocks completion; otherwise use "No issues found." when none exist.

Feature context

During Step 1, prepare one short Feature context brief for the whole change set. Cover the goal and expected behavior, main changes and how they connect, important contracts and constraints, and open questions. Use high-level points rather than a detailed diff summary.
Record the review target and cite the sources of requirements and accepted decisions, such as the user's task, a specification, or a pull request description. Separate stated requirements from observed code behavior. Mark inferred intent and missing context clearly.
Share feature facts and requirements in the brief. Keep candidate findings and reviewer verdicts in candidate-specific messages and reports. Use the brief to understand the feature; establish findings independently from code, source requirements, applicable guidance, and evidence. Shared context does not expand an assigned responsibility or candidate list.
After Step 1, the orchestrator publishes the brief once in a channel for this review with collaboration.post and saves the post's message ID in shared context. In launch context, use that reference in place of the brief's full text. Give every reviewer, review child, validator, and resolver the reference and these instructions. Each recipient reads the full brief with collaboration.read_post before analyzing code and can read it again when needed. Forward the same reference when delegating.
When new authoritative context changes the brief, the orchestrator publishes a complete updated brief and passes its new reference to affected active and later assignments. Preserve completed reproduction evidence and unaffected candidate dispositions. Use Step 2 recovery when the new context changes the basis of a completed disposition.
If required feature context is still missing after checking the brief and available sources, send a focused question to the parent with collaboration.send_message. Continue independent work within the assignment while waiting. If the answer remains unavailable, report the missing context under the existing incomplete-review or human-review rules.
If message-board tools are unavailable, keep the brief in shared context and include its full text in each launch message, including nested assignments. Use the same brief without inheriting conversation history.

Subagent model selection

Apply this policy to every subagent assignment, including planning, review children, validation, and resolution. Leave the user's main-agent model and effort unchanged.
Use the configured subagent defaults for ordinary assignments, including routine final validation, and omit both model and reasoning_effort at launch. The intended baseline is gpt-6.1-sol with xhigh. Routine cross-file tracing, asynchronous UI states, and fixture or guard checks belong on this baseline.
Before choosing stronger settings, collect available context and check the assignment. Split independent responsibilities that compete for attention, but keep interacting contracts together when they need joint analysis.

Choose from these automatic escalations based on the assignment's concrete reasoning difficulty:

Model	Effort	Use when
`gpt-6.1-sol`	`max`	A focused assignment needs a long, well-defined chain of reasoning across files or states.
`gpt-6-astra`	`high`	Available evidence supports competing explanations across interacting contracts that are hard to distinguish, or a well-scoped Sol analysis leaves a specific reasoning problem that stronger expertise can settle with the available evidence.

Select the needed tier directly. Record the chosen settings and concrete reason in routing metadata, outside the scope packet, and pass both model and reasoning_effort explicitly for each escalation.
Return any escalation records with your report so the orchestrator can account for nested assignments.

Reviewer instructions

Before reviewing code, scan the names and descriptions of all available skills, including global and repository-local skills, for relevance to your assigned scope.
Read every relevant skill and its required references before starting the review, then apply that guidance to behavior, conventions, and cleanup decisions. Supplied domain skills are known applicable guidance, not the complete list. Read additional relevant skills when related code brings another domain into scope.
Review only assigned behavior, following relevant code wherever needed; ignore unrelated concerns.
Check assigned code against applicable global and repository instructions, domain practices, and established patterns in comparable code. Every review role owns this check within its scope, including when the code works and tests pass.
Distinguish established conventions from personal preferences. Check that examples serve the same purpose and fit the current language, framework, and supported versions. Respect instruction priority and documented exceptions; do not copy a legacy pattern or a known defect just for consistency.
Support each finding with an exact code location and evidence. For a defect, show a concrete trigger and consequence. For a practice or consistency violation, cite the applicable rule or comparable code and explain the deviation; a proven convention violation does not need a runtime failure. A general best-practice claim needs a concrete benefit or risk in the assigned code, not preference alone. Use supplied validation as context and return claims that code inspection cannot settle as unresolved candidates.
Merge duplicate root causes into one candidate list, assign a stable ID to every candidate, and do not remove a supported candidate because it is low priority, cosmetic, readability-related, or easy to fix.
Keep findings, incomplete reviews, and human-review candidates separate. Use human review for material decisions or confirmations requiring project context unavailable in the repository; use incomplete review when technical analysis is unfinished. Include the location, missing context, consequence, and required human action.

Compact reviewer instructions

Review one combined packet directly across all assigned roles and domain skills; spawn no children or validators.
Return candidates and evidence to the orchestrator; if none exist, return checked scope and "No issues found."
Mark unfinished responsibilities incomplete with missing context or expertise and completed scope; do not guess.

Specialist instructions

Give each child a self-contained narrower assignment marked as internal, with the feature context instructions and brief reference, reviewer instructions, and applicable guidance for its scope, and instruct it to work directly without invoking code-review orchestration. Do not pass these general specialist instructions or the specialist role; the specialist alone controls the child's prompt, scope, evidence contract, and lifecycle.
Delegate one coherent responsibility, not individual checklist items, and verify child evidence before merging it into the candidate list.
When the merged candidate list is empty, return checked scope and "No issues found." without spawning a validator.
When the merged candidate list is nonempty, spawn exactly one fresh final finding validator with fork_turns="none". Mark the assignment as internal and give it the exact candidate list with IDs, code scope, prior evidence and reproduction results, feature context instructions and brief reference, applicable guidance, and final finding validator instructions.
Return every validator-confirmed finding with its stable ID. Keep validator-rejected candidates out of findings, and return validator-unresolved candidates separately as an incomplete review.

Final finding validator instructions

Perform this internal assignment directly without invoking code-review orchestration. Review only the supplied candidates and code needed to validate them; do not search for new findings or spawn children.
Before inspecting code to validate candidates, scan the names and descriptions of all available skills, including global and repository-local skills, then read every relevant skill and its required references. Apply that guidance when confirming or rejecting findings. Supplied guidance does not replace this skill check.
Independently establish or refute each candidate from its code location and evidence. For defects, check the trigger and consequence. For practice or consistency violations, check the rule or comparable examples, their applicability and exceptions, and the deviation. Do not require a runtime failure for a proven convention violation or accept personal preference as a rule. Reuse supplied evidence and reproduction results; only when they have not settled a claim, run the smallest new read-only reproduction once.
Preserve every candidate ID and return exactly one disposition for each: Confirmed with supporting evidence, Rejected with contradicting evidence, or Unresolved with the missing context or validation needed.
Do not suppress or downgrade a confirmed candidate because it is low priority, cosmetic, readability-related, or easy to fix. Priority is assigned after validation.

Workflow

Step 1: Select review mode and assignments

Use one subagent with fork_turns="none" for this internal planning task to identify review source: branch, commit, pull request, or uncommitted changes. Give it the applicable global and user instructions already available to the orchestrator, available feature requirements and accepted decisions with their sources, the feature context instructions, and the subagent model selection policy. Unless the user specifies one, review all uncommitted changes when any exist; otherwise fetch the remote default branch and review the entire current branch against its fresh remote-tracking ref.
Collect applicable guidance for the changed code: global user instructions, root and nested repository instructions, relevant documentation and tool configuration, and domain skills. Inspect nearby code and shared helpers for established patterns in comparable implementations. Record each rule or pattern with its source and scope, including relevant exceptions; resolve conflicts by instruction priority. Keep this guidance in shared context and pass the relevant parts to reviewers, children, validators, and resolvers instead of relying on inherited conversation history.
Select compact only for one clearly local, simple, low-risk, self-contained responsibility that one generalist can review from one packet. Use specialist for authorization, security, privacy, destructive or transactional data changes, concurrency, migrations, public or cross-system contracts, backward compatibility, infrastructure, any other material risk, or uncertain classification.
File or line count may rule out compact but never justify it.
Assign every applicable review role to an explicit owner. For substantial UI or state changes with substantial tests, give product behavior and test protection separate focused assignments, with frontend interaction covered where applicable. Combine compatible roles for small, coherent assignments.
Return one review plan containing: shared context with the review source and target, the feature context brief, exactly one selected mode and reason, changed behavior or contracts, entry points, Available validation evidence, and applicable guidance; reviewer routing that maps each packet to its assigned review roles, known applicable domain skills, and any model escalation with its reason; and assignment packets that contain only a coherent responsibility and relevant code or context.
Give compact exactly one packet covering every change. Give specialist one named packet per specialist, overlapping only for cross-target behavior. Keep the selected mode in shared context. Do not copy nested-assignment lifecycle markers such as internal or direct-execution restrictions into first-level packets or routing; they apply only where the child or validator instructions explicitly require them.
Return only the review plan. Leave reviewer launches and candidate findings, including suspected defects, to Step 2.

Step 2: Assign reviewers and perform review

For compact, build one launch envelope from the shared context, routing, and single packet, then spawn one fresh compact reviewer. If its candidate list is nonempty, spawn one fresh final finding validator with the exact candidate list and IDs, packet code scope, prior evidence, feature context instructions and brief reference, applicable guidance, and validator instructions. Preserve the reviewer's completed and incomplete scope.
For specialist mode, build one launch envelope per routed packet and spawn one fresh subagent per selected specialist, in batches when necessary to leave capacity for specialist-owned children.
Collect validated reviewer reports and reproduction results. If new context or expertise can settle unresolved IDs, or new authoritative context changes the basis of a completed disposition, give one fresh resolver with fork_turns="none" only those affected candidate IDs, all prior evidence, feature context instructions and brief reference, and applicable guidance with its sources, scope, and exceptions. Never rerun the reviewer assignment, repeat a completed reproduction, or revisit unaffected IDs. Replace affected dispositions with the resolver's results; keep still-unresolved candidates separate as an incomplete review.

Step 3: Produce final review report to user

Build a finding ledger from the current validated dispositions, using each resolver's result in place of the prior disposition for that stable ID. Merge confirmed IDs only when they describe the same root cause. If validated reports still conflict, give one fresh resolver with fork_turns="none" only the conflicting candidate IDs, prior evidence, feature context instructions and brief reference, and applicable guidance with its sources, scope, and exceptions before finalizing. Resolvers follow the final finding validator instructions.
Outside that conflict path, do not inspect code, rerun validation, or spawn agents during Step 3; deduplication alone never justifies a resolver.
Account for every confirmed ID exactly once as its own final finding or as a source of an explicitly merged final finding. Do not omit confirmed findings because of priority, materiality, report length, readability, or ease of cleanup; priority only controls ordering and labels.
Reconcile the ledger before responding and report a compact accounting line with confirmed review findings, final comments, duplicate merges, and omitted findings. The omitted count must be zero.
Report review target, selected mode, actual reviewers and validators used, any model escalations with their reasons, findings summary, every confirmed detailed comment, and a verified, deduplicated Human review section; use None. when no human review is required.

Review roles

Behavioral and contract

Review behavioral logic, state transitions, cross-file behavior, regressions, API contracts, and backward compatibility.

Data and concurrency

Review data loss, invalid lifecycle transitions, transaction boundaries, idempotency, races, and production-data assumptions.

Security and vulnerability

Review concrete attacker paths, authorization mistakes, unsafe data exposure, and security consequences.

Privacy and data protection

Review privacy violations, data leaks, and unsafe data handling.

Performance and resource usage

Review time and space complexity, algorithmic efficiency, caching, and resource management under supported workloads.

Test and regressions

Review whether tests protect the intended contract, fail when that contract is removed, and cover material negative cases. Check that fixtures, mocks, and shared guards exercise the changed path and that assertions distinguish the required behavior from plausible incorrect outcomes.

Waste and maintainability

Review assigned non-style dead, duplicate, temporary, or speculative code and artifacts directly.
Compact reviewers also review readability and style waste directly using applicable language, framework, and CSS skills; they do not spawn children.
Waste specialists partition the scope into non-style and style-bearing sections without reviewing style waste directly.
If non-style code exists, spawn one readability child for the combined scope. Give it the exact code scope, applicable repository and language or framework instructions, and code readability reviewer instructions; verify and merge its evidence.
If style-bearing code exists, spawn one CSS child for the combined scope. Give it the exact style scope, applicable CSS skill, and CSS waste reviewer instructions; verify and merge its evidence.

Code readability reviewer instructions

Perform this internal assignment directly without invoking code-review orchestration or spawning children; review only the supplied code scope.
Follow the supplied repository and applicable language or framework instructions.
Find code whose intent or execution order is materially obscured by dense expressions, nesting, mixed abstraction levels, misleading names, or unnecessary indirection. Treat these as signals, not an exhaustive checklist.
Recommend the smallest correction that preserves behavior and supported performance characteristics. Report proven convention violations even in simple code; do not report personal formatting preferences.
Report checked scope and actual findings with exact locations and supporting evidence; return "No issues found." when none exist.

CSS waste reviewer instructions

Perform this internal assignment directly without invoking code-review orchestration or spawning children; review only the supplied style scope.
Follow the applicable CSS skill and repository browser targets, build configuration, resets, and nearby styling context.
Find dead or duplicate selectors and declarations.
Find declarations proven ineffective by the cascade, inheritance, or layout context.
Find repeated global or base styles and compatibility workarounds outside declared browser targets.
Report checked scope and actual findings with exact locations and supporting evidence; return "No issues found." when none exist.

Frontend and user experience

Review user-visible states, accessibility, interaction behavior, layout risks, and visual regressions. Follow keyboard focus and visible feedback through state changes, including asynchronous responses and replacement controls.