Code Review

Code Review

Orchestrate a multi-agent code review pipeline: research the changes, optionally investigate external alternatives, dispatch parallel domain-specific reviewers, and synthesize everything into a structured report.

Input Collection

Prompt the user to select an input mode. Present these options clearly:

What would you like me to review?

1. Current PR — review the open PR on this branch (description + diff)
2. Diff to main — review all uncommitted and committed changes vs main
3. Specific paths — review specific files, crates, or directories

Pick a number, or describe what you'd like reviewed.

Collecting the diff

Mode 1 — Current PR:

gh pr view --json title,body,number,baseRefName
gh pr diff

If no open PR exists, tell the user and suggest mode 2 instead.

Mode 2 — Diff to main:

git diff main...HEAD

Also include git log main..HEAD --oneline for commit context.

Mode 3 — Specific paths: Ask the user for paths. Read the specified files directly. No diff — review the code as-is.

Store the collected input (diff text, PR description, file contents) for use in subsequent phases.

Handling large diffs

If the diff exceeds ~2000 lines, save it to a temporary file (/tmp/code-review-diff.patch) and have agents read it via the Read tool rather than inlining it in their prompts. This prevents context overflow. Reference the file path in agent prompts instead of pasting the diff.

Phase 1: Research & Domain Mapping

Spawn an Agent (subagent_type: general-purpose) and include the full text of the research-codebase skill instructions in its prompt (read .claude/skills/research-codebase/SKILL.md first). Direct the agent to research the changes with this focus:

• Map all changed files to their logical domains and crate boundaries
• Identify which changes are Rust code vs non-Rust (CI, docs, config, TypeScript SDK, nix, etc.)
• Understand the architectural context around each change — what traits, types, and modules are involved
• Group changes into at most 4 logical domain groups, merging smaller related changes together
• Flag any changes that warrant external web research:
  • New dependencies or crate additions
  • Unfamiliar architectural patterns
  • Potentially deprecated API usage
  • Cases where alternative approaches might exist

The research agent will internally spawn codebase-locator, codebase-analyzer, and codebase-pattern-finder sub-agents. You do not need to manage those agents directly.

Parse the research output for:

1. Domain groups — a list of 1-4 logical clusters, each with:

   • A descriptive name (e.g., "OAuth token refresh flow", "adapter registry refactor")
   • The files and line ranges involved
   • Key context (traits, types, modules, patterns in play)
   • Whether changes are Rust or non-Rust

2. Web research questions — specific questions worth investigating, or empty if none

3. Change characterization — new feature, refactor, bugfix, etc., to help reviewers calibrate

Phase 2: Web Research (conditional)

Skip this phase entirely if Phase 1 flagged no web research questions.

If questions were flagged, spawn web-search-researcher agent(s) with the specific questions. Each agent should:

• Search for the specific concern (e.g., "ring crate security advisories 2026", "tokio channel vs crossbeam performance comparison")
• Return findings with source links
• Focus on actionable information relevant to the review

If web research fails or times out, proceed to Phase 3 without it. Note the failure in the final report.

Phase 3: Parallel Review Agents

Spawn all review agents in a single message so they run concurrently. Every agent receives:

• The full diff (or file contents for mode 3)
• The research context from Phase 1 (domain map, architectural context)
• Web research findings from Phase 2 (if any)
• The PR description (if mode 1)

Path-triggered guardrails (apply BEFORE building agent prompts)

If the diff touches any of these paths, the command catalog guardrails apply and MUST be propagated into every reviewer's prompt:

• crates/rote-cli/src/cli/parser/parsers/<family>/{mod,spec,tests}.rs
• crates/rote-cli/src/cli/parser/spec/*.rs
• crates/rote-search/src/builder/commands.csv
• crates/xtask/src/gen_artifacts.rs

When this trigger fires:

1. Read .claude/skills/command-catalog-guardrails/SKILL.md and extract its checklist + drift-class table.
2. Append both verbatim to every Phase 3 agent prompt (rust-engineer, general-purpose, codex-second-opinion). Each agent must explicitly evaluate the diff against every checklist item and call out failures in its findings table.
3. In the synthesis report, add a "Catalog Guardrails" section above "Critical" listing any checklist items the agents flagged. Use it to make catalog drift visible separately from generic Rust review findings — the failure modes (silent value drop, help-before-validate, positional ignored) don't fit cleanly into the standard severity buckets.