review

name	review
description	Structured code review using tiered persona subagents, confidence-gated findings, and a merge/dedup pipeline. Use when reviewing code changes before creating a PR, as a build gate, or for standalone review.
argument-hint	[mode:autofix|mode:report-only] [branch name or file paths]

Code Review

Reviews code changes using dynamically selected reviewer personas. Spawns persona subagents that return structured findings, then merges and deduplicates into a unified report.

Agent-Intercom Communication (NON-NEGOTIABLE)

Call ping at session start. If agent-intercom is reachable, broadcast at every step. If unreachable, warn the user that operator visibility is degraded.

When the strict-safety capability pack is installed, also follow .github/instructions/strict-safety.instructions.md: for high-risk diffs, call out the ProposedAction, ActionRisk, approval, and rollback gaps that should be visible before merge or deployment.

Event	Level	Message prefix
Review start	info	[REVIEW] Starting {mode} review of {scope}
Diff analyzed	info	[REVIEW] Analyzed diff: {file_count} files, {line_count} lines changed
Persona routing	info	[REVIEW] Routing: {always_on_count} always-on + {conditional_count} conditional personas
Persona spawned	info	[SPAWN] {persona_name} for code review
Persona returned	info	[RETURN] {persona_name}: {finding_count} findings
Merge complete	info	[REVIEW] Merged: {total} findings ({p0} P0, {p1} P1, {p2} P2, {p3} P3)
Autofix applied	info	[REVIEW] Applied safe_auto fix: {finding_summary}
Review written	success	[REVIEW] Review artifact: {file_path}
Waiting for input	warning	[WAIT] Blocked on user decision
Review complete	success	[REVIEW] Complete: {summary}

Subagent Depth Constraint

This skill spawns reviewer subagents. Those subagents are leaf executors and MUST NOT spawn their own subagents. Maximum depth: review skill → persona subagent (1 hop).

Mode Detection

Check arguments for mode:autofix or mode:report-only. Strip the mode token before interpreting remaining arguments.

Mode	When	Behavior
Interactive (default)	No mode token	Review, present findings, ask for decisions
Autofix	mode:autofix	No user interaction. Apply safe_auto fixes only, write artifact, emit residual work
Report-only	mode:report-only	Read-only. Report findings plus a readiness verdict, with no edits or follow-up item creation

Autofix mode rules

• Skip all user questions
• Apply only safe_auto findings
• Leave gated_auto, manual, and advisory findings unresolved
• Write a review artifact to docs/closure/
• Create backlog follow-up items for unresolved actionable findings
• Record a readiness outcome: READY, READY_WITH_FOLLOWUPS, or BLOCKED
• Never commit, push, or create a PR

Report-only mode rules

• Skip all user questions
• Never edit files
• Return structured findings plus a readiness outcome to caller
• Do not write a review artifact
• Do not create backlog follow-up items
• Safe for the ship agent to invoke during the build loop

Severity Scale

Level	Meaning	Build gate action
P0	Critical breakage, exploitable vulnerability, data corruption	Block commit
P1	High-impact defect in normal usage, breaking contract	Block commit
P2	Moderate issue (edge case, perf, maintainability)	Record as backlog follow-up item
P3	Low-impact, minor improvement	User's discretion

Action Routing

Class	Default owner	Meaning
safe_auto	Review skill (autofix mode)	Deterministic local fix
gated_auto	agent-intercom approval	Fix exists but changes behavior/contracts
manual	Backlog follow-up item	Actionable work requiring human judgment
advisory	Informational	Learnings, rollout notes, residual risk

Routing rules:

• Choose the more conservative route on disagreement between personas
• Only safe_auto findings enter the autofix queue
• requires_verification: true means a fix needs tests or re-review

Readiness Outcome Contract

Every review run must produce one of these outcomes for the reviewed HEAD:

Outcome	Meaning	Ship / PR action
READY	Zero unresolved P0/P1 findings and no required follow-up items	PR may be prepared
READY_WITH_FOLLOWUPS	Zero unresolved P0/P1 findings, but one or more P2/P3 findings need explicit follow-up tracking or residual-risk notes	PR may be prepared only with follow-up handling recorded
BLOCKED	One or more unresolved P0/P1 findings remain	Do not create or present a PR

The readiness summary must include:

• reviewed HEAD SHA or equivalent diff identity
• counts for P0, P1, P2, and P3 findings
• follow-up item IDs or residual-risk notes when outcome is READY_WITH_FOLLOWUPS
• whether runtime verification follow-up is required

Local Review Readiness and Dark Mode

This readiness outcome is the local review record consumed by Ship and pr-lifecycle before PR presentation. When DARK_MODE_ACTIVE is present under P-017, this local review record is the authoritative merge-readiness signal:

• unresolved P0/P1 findings always produce BLOCKED
• READY_WITH_FOLLOWUPS must include concrete follow-up item IDs or explicit residual-risk notes
• hosted Copilot/GitHub review cannot replace this local review record
• advisory shadow-review comments are follow-ups by default unless the operator or policy explicitly elevates them to blocking status
• the reviewed HEAD SHA or equivalent diff identity must be current when the PR readiness block is written

Reviewer Personas

Always-On (every review)

Persona Subagent	Focus
Constitution Reviewer	Constitutional compliance
Rust Reviewer	Language-specific safety and correctness
Correctness Reviewer	Logic errors, edge cases, and behavioral correctness
Maintainability Reviewer	Complexity, coupling, and premature abstraction
Learnings Researcher	Search compound library for related past issues

Conditional (based on changed files)

Use a different model from the caller when available to force genuine diversity of critique. Cross-model is preferred but not blocking.

Persona Subagent	Select when diff touches	Suggested Model
Architecture Strategist	Module boundaries, new abstractions, dependency changes	Different from caller
Concurrency Reviewer	Concurrent/async patterns	Different from caller
Scope Boundary Auditor	Changes spanning multiple domains or exceeding expected scope	Different from caller
Agent-Native Parity Reviewer	MCP SDKs, tool handlers, agent-exposed actions, or user/agent parity-critical flows	Different from caller
Security Reviewer	Auth middleware, public endpoints, input handling, permission checks, secret management	Different from caller
Template Integrity Reviewer	.tmpl files, Markdown workflow assets, generated artifact references, or policy/instruction surfaces	Different from caller
Schema-CLI-Docs Coupling Reviewer	Cross-domain diffs spanning schemas, CLI verification logic, install/tune skills, and operator docs	Different from caller

Workflow

Step 1: Determine Review Scope

1. Identify changed files from git diff, explicit file list, or caller-provided scope
2. Categorize each file by type and domain
3. Identify which instruction files apply (via applyTo patterns)
4. Broadcast the diff analysis

Step 2: Route Personas

1. Always-on: spawn Constitution Reviewer, Rust Reviewer, Correctness Reviewer, Maintainability Reviewer, Learnings Researcher
2. Conditional: analyze changed file paths, content patterns, and workspace agent-native signals to select additional personas:
   • Select Security Reviewer (security-reviewer.agent.md) when the diff touches: authentication or authorization code, public endpoint handlers, user input processing, permission or role checks, secret or credential management, or content matching these patterns: unsafe blocks without SAFETY comments, unchecked deserialization, raw SQL in embedded DB, unvalidated file paths, secrets in config
   • Select Template Integrity Reviewer (template-integrity-reviewer.agent.md) when the diff touches template files, Markdown harness artifacts, review/policy/instruction assets, or generated-artifact reference tables
   • Select Schema-CLI-Docs Coupling Reviewer (schema-cli-docs-coupling-reviewer.agent.md) when the diff spans schema files, src/ verification logic, install/tune skills, or operator-facing documentation in the same change set
3. Broadcast the routing decision with persona count

Step 3: Spawn Persona Subagents

Spawn all selected personas. Each receives:

• The list of changed files with line ranges
• The diff content relevant to their domain
• Instructions to return structured findings
• Codebase search directive (use grep/glob for context)

Broadcast each spawn.

Step 4: Collect and Merge Findings

As each persona returns:

1. Broadcast the return with finding count
2. Collect all findings
3. Deduplicate: merge findings that identify the same issue
4. Assign final severity (more conservative on disagreement)
5. Assign final action routing
6. Derive the readiness outcome:
   • BLOCKED if any unresolved P0/P1 findings remain
   • READY_WITH_FOLLOWUPS if P0/P1 is clear but actionable P2/P3 findings require backlog follow-up or explicit residual-risk notes
   • READY otherwise

Step 5: Apply Actions (mode-dependent)

Interactive mode:

1. Present findings grouped by severity (P0 first)
2. For each P0/P1, ask the user to accept, modify, or reject the recommendation
3. Apply approved fixes

Autofix mode:

1. Apply all safe_auto findings automatically
2. Create backlog follow-up items for unresolved actionable findings
3. Write review artifact to docs/closure/
4. Include the readiness outcome, reviewed HEAD, and follow-up item IDs in the artifact

Report-only mode:

1. Return structured findings and the readiness outcome to caller
2. No side effects: no edits, no review artifact, no follow-up items

When the diff changes runtime surfaces, include an explicit recommendation for whether follow-up runtime verification is required and which mode (manual, api, browser) is appropriate.

When the diff includes destructive potential, contract changes, migrations, security-sensitive edits, or other high-blast-radius work, include an explicit recommendation for whether strict-safety action classification or approval follow-up is required before merge or deployment.

When the adversarial-review capability pack is installed and this review surfaces 3 or more P0/P1 findings, recommend escalation to the adversarial-review agent for multi-model consensus validation before blocking the build.

Quality Criteria

• Every changed file is reviewed by at least the always-on personas
• All P0 findings are addressed before the review is marked complete
• P1 findings require explicit acknowledgment (fix or defer with rationale)
• The review report accurately reflects all findings and their resolution status

Model Routing

This skill operates at Tier 2 (Standard) — review coordination and finding assembly.

Generated by autoharness | Template: review/SKILL.md.tmpl