# Review > Dispatch reviews to external companion AIs (Codex, Gemini, Claude) for an independent second opinion on code changes, PR readiness, doc completeness, architecture, or implementation status. Use when you want a fresh-eyes review beyond Claude-native. Trigger on "get a second opinion", "companion review", "review my changes", "review the PR". For Claude-only quality checks use /code-review. - Skill: `gabrielmoreira/review-4` (Agent Skill) - Install (CLI): `npx skillmds@latest add gabrielmoreira/review-4` - Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/review-4/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/gabrielmoreira/review-4 --- # 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 # PRP/PRD/RFC/Design completeness review /review solve "problem" # Architecture/design second opinion /review status # Implementation progress vs spec /review frontend # 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 ```bash : "${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 ```bash : "${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`: ```bash : "${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: ```bash # 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:** ```bash : "${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`):** ```bash 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) ```bash # 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)