Review — Companion-Dispatched Reviews & Analysis

Unified skill for all companion AI reviews. Dispatches structured prompts to external AIs (Codex, Gemini, Claude) via runner.sh for independent second opinions.

For Claude-native code quality checks (no external AI), use /code-review.

Usage

/review                              # Auto-detect: uncommitted changes → changes review
/review changes                      # Full review: code + silent-failures + types + comments
/review changes --quick              # Code review only (skip silent-failures/types/comments)
/review pr [--pr N]                  # PR merge readiness (MERGE/BLOCK verdict)
/review doc <file>                   # PRP/PRD/RFC/Design completeness review
/review solve "problem"              # Architecture/design second opinion
/review status <spec>                # Implementation progress vs spec
/review frontend <url>               # Delegates to /frontend review
/review silent-failures [file|diff]  # Error handling audit
/review types [file]                 # Type design analysis
/review comments [file]              # Comment accuracy check
/review gate                         # Lightweight pre-commit gate (critical bugs + security only)
/review adversarial                  # Adversarial review: challenge design choices (Codex gpt-5.5 xhigh)

All subcommands support: [companion] (codex/gemini/claude), --model MODEL, --all, --exclude-self

Workflow

Step 1: Parse Arguments

Parse $ARGUMENTS for subcommand and flags:

• First positional arg → subcommand (changes, pr, doc, solve, status, frontend, silent-failures, types, comments, gate, adversarial)
• If no subcommand: check for uncommitted changes → default to changes, else show usage
• Companion name: codex, gemini, or claude (optional, resolved from registry defaults)
• --model MODEL → override default model
• --base BRANCH → diff against branch (for changes/pr)
• --pr NUMBER → GitHub PR mode (for pr subcommand)
• --context FILE → attach context files (for solve)
• --type PRP|PRD|RFC|DESIGN → doc type override (for doc)
• --issue NUMBER → GitHub issue (for status)
• --timeout SECS → override default timeout
• --all → dispatch to all installed companions in parallel
• --exclude-self → exclude claude from --all runs
• --quick → code review only (for changes: skip silent-failures/types/comments checks)

Step 2: Resolve Companion

: "${HOME:=$(eval echo ~)}"
DEFAULT_COMPANION=$(bash "$HOME/.claude/shared/companions/lib/resolve-default.sh" "$CAPABILITY")
COMPANION="${COMPANION:-$DEFAULT_COMPANION}"

Where $CAPABILITY maps from subcommand:

• changes → review
• pr → pr-review
• doc → doc-review
• solve → solve
• status → implementation-status
• gate → review
• silent-failures, types, comments → review

Step 3: Check Availability

: "${HOME:=$(eval echo ~)}"
cat "$HOME/.claude/shared/companions/registry.json" | jq -r ".companions.$COMPANION.installed"

If not installed, report error with install instructions from registry.

Step 4: Dispatch by Subcommand

Load the prompt template from templates/ and dispatch:

Subcommand	Template	Input	Capability
changes	templates/changes.md	git diff (uncommitted or branch)	review
pr	templates/pr.md	gh pr diff or git diff base...HEAD	pr-review
doc	templates/doc.md	File content + type-specific criteria	doc-review
solve	templates/solve.md	Problem description + context files	solve
status	templates/status.md	Reference doc/issue + codebase access	implementation-status
gate	templates/gate.md	git diff HEAD (lightweight, critical only)	review
adversarial	templates/adversarial.md	git diff HEAD (uncommitted)	review
silent-failures	templates/silent-failures.md	File content or diff	review
types	templates/types.md	File content	review
comments	templates/comments.md	File content	review

Diff collection for changes, adversarial, and gate: use the shared adaptive collector rather than raw git diff:

: "${HOME:=$(eval echo ~)}"
COLLECT_ARGS="--uncommitted"
[[ -n "$BASE_BRANCH" ]] && COLLECT_ARGS="--base $BASE_BRANCH"
DIFF=$(bash "$HOME/.claude/shared/companions/lib/collect_diff.sh" $COLLECT_ARGS)

This applies three-tier sizing automatically (full / per-file-truncated / stat+top10).

Each template contains the full prompt structure. Read the template for the prompt format, then build the prompt in bash using variable expansion. NEVER use sed for interpolation — diff content breaks sed delimiters. Instead:

# Build prompt by assembling sections directly (NOT by sed-replacing template vars)
PROMPT="You are a senior code reviewer...

Scope: $SCOPE
$TRUNCATION_WARNING

[rest of prompt from template]

--- DIFF ---
$DIFF"

# Write to temp file for large prompts (>50K)
echo "$PROMPT" > /tmp/review_prompt.txt
cat /tmp/review_prompt.txt | bash "$HOME/.claude/shared/companions/runner.sh" ...
rm /tmp/review_prompt.txt

The template shows the prompt structure and variables. Copy the prompt text from the template's ```prompt block, substitute variables inline via bash "$VAR" expansion, and pipe to runner.sh.

Step 5: Dispatch via Runner

Single companion:

: "${HOME:=$(eval echo ~)}"
RUNNER_ARGS="$COMPANION --capability $CAPABILITY --timeout $TIMEOUT"
[[ -n "$MODEL" ]] && RUNNER_ARGS+=" --model $MODEL"
echo "$PROMPT" | bash "$HOME/.claude/shared/companions/runner.sh" $RUNNER_ARGS

IMPORTANT: Do NOT pass --model default or --model "". Omit --model entirely when no user override is specified — runner.sh resolves from registry automatically.

Adversarial subcommand: always add --structured --model gpt-5.5 --reasoning xhigh to RUNNER_ARGS. Load the template from ~/.claude/shared/companions/templates/adversarial.md, substitute $REVIEWER_CONTEXT with "second opinion for Claude", and substitute $DIFF / $SCOPE / $TRUNCATION_WARNING as usual.

Gate subcommand: use the fast codex review - path (no --structured). Parse PASS/BLOCK from the text output with grep. Timeout: 120s. Do NOT add --structured — codex exec review --output-schema has more latency than the native review mode and defeats the purpose of a fast gate.

Multi-companion (--all):

MULTI_ARGS="--capability $CAPABILITY --timeout $TIMEOUT"
[[ -n "$MODEL" ]] && MULTI_ARGS+=" --model $MODEL"
$EXCLUDE_SELF && MULTI_ARGS+=" --exclude-self"

: "${HOME:=$(eval echo ~)}"
MULTI_OUTPUT=$(echo "$PROMPT" | bash "$HOME/.claude/shared/companions/multi-runner.sh" $MULTI_ARGS)

Step 6: Present Output

Display companion output directly in the conversation. Never write to files.

Single companion:

══════════════════════════════════════
REVIEW: [Subcommand] — [Companion] ([model])
Target: [scope description]
══════════════════════════════════════

[companion output]

══════════════════════════════════════

Multi-companion:

══════════════════════════════════════
MULTI-COMPANION REVIEW: [Subcommand]
Target: [scope description]
══════════════════════════════════════

[multi-runner output — each companion labeled]

══════════════════════════════════════

Step 7: Analysis

After presenting companion output, add:

Extended Analysis — For each finding:

• Agree/disagree with companion, with reasoning
• Additional codebase context
• Severity assessment

Action Plan — Prioritized checklist ordered by severity. Skip false positives.

For --all mode, perform consensus analysis instead:

• UNANIMOUS: All companions agree → high confidence
• MAJORITY: >50% agree → strong signal
• SOLO: Only one flagged → validate manually
• CONFLICTING: Companions disagree → needs human judgment

Special: /review frontend

Delegates to /frontend review. Display message:

Delegating to /frontend review — visual design review requires Gemini multimodal.
Run: /frontend review [url] [--full-page] [--color-scheme MODE]

Default: /review changes (full review)

By default, /review changes runs the standard code review prompt PLUS appends checks from:

• templates/silent-failures.md (error handling audit)
• templates/types.md (type design analysis)
• templates/comments.md (comment accuracy)

Special: /review changes --quick

Skips silent-failures, types, and comments checks. Runs only the standard code review prompt from templates/changes.md. Use when you want a fast review and don't need the deeper audits.

Diff Handling (shared by changes, pr, gate)

# Determine diff
if [[ -n "$BASE_BRANCH" ]]; then
  DIFF=$(git diff "$BASE_BRANCH"...HEAD)
  SCOPE="branch diff: $(git branch --show-current) vs $BASE_BRANCH"
elif [[ -n "$PR_NUMBER" ]]; then
  DIFF=$(gh pr diff "$PR_NUMBER")
  SCOPE="PR #$PR_NUMBER"
else
  DIFF=$(git diff HEAD)
  SCOPE="uncommitted changes"
fi

# Empty check
if [[ -z "$DIFF" ]]; then
  echo "No changes to review."
  exit 0
fi

# Size guard — truncate at 100K chars
DIFF_LEN=${#DIFF}
if [[ $DIFF_LEN -gt 100000 ]]; then
  DIFF="${DIFF:0:100000}"
  TRUNCATION_WARNING="WARNING: Diff truncated from $DIFF_LEN to 100,000 characters."
fi

Default Timeouts

Subcommand	Default Timeout	Reason
changes	300s	Standard review
pr	300s	Standard review
doc	300s	Standard review
solve	300s	Standard analysis
status	600s	Deep codebase exploration
gate	120s	Lightweight, pre-commit speed
silent-failures	300s	Standard analysis
types	300s	Standard analysis
comments	300s	Standard analysis

Critical Rules

0. Failure policy — one companion, no substitution, no workarounds.

   • Hard failures (auth error, model-not-found, empty output, non-zero exit): report the exact error and stop. Do NOT retry.
   • Transient failures (timeout, exit 124, rate-limit 429): retry the same companion once only. If it fails again, stop and report.
   • Never switch to a different companion after any failure.
   • Never fall back to Claude's own analysis, /code-review, or any other native review path. The point is an independent second opinion — any Claude-generated review defeats the purpose. Report the failure and let the user decide the next step.
   • This applies to all subcommands and all companions (codex, gemini, claude).

1. All companions use runner.sh. No native path for any companion. Codex goes through codex exec via runner.sh.

2. Guard $HOME in every bash block: : "${HOME:=$(eval echo ~)}". Then use $HOME (not ~) in all paths.

3. Display output directly. Never write to plan files, markdown files, or any other file.

4. Codex may hallucinate success (especially in status assessments). Always cross-reference evidence paths. Treat output as advisory, not authoritative.

Error Handling

• No changes to review → "No changes to review" and stop
• Missing required input (file path, problem description, reference) → report what's needed and stop
• Companion not installed → report with install instructions from registry
• Companion timeout → report timeout, suggest narrowing scope
• Empty/one-line output → report insufficient output and stop
• gh CLI not available (for --pr/--issue) → report GitHub CLI required

Integration

Invoked by: User directly (/review), /pre-commit step 5 (/review gate) Infrastructure: ~/.claude/shared/companions/ (runner.sh, multi-runner.sh, registry.json, lib/) Claude-native alternative: /code-review (for fast, local quality checks without external AI) Related: /frontend review (visual design review via Gemini multimodal)