reviewing-code

name	reviewing-code
description	Reviews the current branch against a base ref using multiple AI backends. Routes discovery, discovery-secondary, remediation, and verify passes through the available agents (codex, claude, opencode, kimi, …), gracefully skipping any backend that isn't installed. Writes a markdown findings report under docs/. Use when preparing or updating a PR, before merging a feature branch, or when wanting an independent second opinion from a different agent.
user-invocable	true
allowed-tools	Read, Grep, Glob, Bash(node:*), Bash(git:*), Bash(command -v:*)
model	claude-opus-4-8
context	fork

reviewing-code

Four-pass multi-agent code review of the current branch against a base ref. Each pass is a separate agent run with a focused prompt; the results fold into one markdown report.

When to use

• Reviewing a feature branch before opening (or after updating) a PR.
• Getting a second-and-third opinion from a different agent than the one currently editing.
• Surfacing real bugs / regressions / data-integrity issues, not style.
• Establishing a paper trail for a tricky migration or compatibility-path change.

Default pipeline

Pass	Role	Default backend	Output
1	discovery	codex	overwrites report
2	discovery-secondary	codex	merges into report (skipped if no new findings)
3	remediation	codex	adds Suggested Fix + Suggested Regression Tests per finding
4	verify	claude	appends ## <Backend> Verification section

Per-role fallback order, hybrid-backend handling (opencode), and the graceful-detect / skip-with-note policy live in _shared/multi-agent-backends.md. This skill is the canonical implementation of that contract.

Variant analysis on confirmed findings

For every High / Critical finding the verify pass marks CONFIRMED, run a variant search before closing the report. The same shape often hides elsewhere in the repo. The discipline (what to search for, how to scope, when to skip) lives in _shared/variant-analysis.md. Append a ## Variant Analysis section per finding when variants are found; omit the section when there are none rather than emit an empty header.

For security-class diffs specifically, run scanning-quality/scans/differential.md alongside this skill. That scan is the security-regression cousin to this skill's general review.

Compounding lessons

When the same review finding has fired in two consecutive runs (or across two repos), promote it to a fleet rule per _shared/compound-lessons.md. Don't keep catching the same bug; codify it once.

Usage

# Default: codex×3 + claude×1, output under docs/<branch-slug>-review-findings.md
node .claude/skills/reviewing-code/run.mts

# Custom base
node .claude/skills/reviewing-code/run.mts --base origin/main

# Custom output
node .claude/skills/reviewing-code/run.mts --output docs/reviews/my-branch.md

# Skip the verify pass entirely
node .claude/skills/reviewing-code/run.mts --skip-verify

# Override one or more passes
node .claude/skills/reviewing-code/run.mts --pass discovery=kimi --pass verify=opencode

# Cleanup the temp dir on exit (default keeps logs for inspection)
node .claude/skills/reviewing-code/run.mts --cleanup-temp

# Run only a subset of passes
node .claude/skills/reviewing-code/run.mts --only discovery,verify

Configuration via env vars

Var	Default	Effect
CODEX_MODEL	gpt-5.4	Codex model when codex is the active backend
CODEX_REASONING	xhigh	Codex reasoning effort
CLAUDE_MODEL	opus	Claude model when claude is the active backend
KIMI_MODEL	kimi-latest	Kimi model when kimi is the active backend

Output

A single markdown file (docs/<branch-slug>-review-findings.md by default) with this structure:

# <descriptive title>
## Scope
## Executive Summary
## Findings
### 1. <title>
   Severity, Summary, Affected Code, Why This Is A Problem, Impact,
   Suggested Fix, Suggested Regression Tests
## Assumptions / Gaps
## Validation Notes
## Suggested Next Steps
---
## <Backend> Verification
   Per-finding verdict (CONFIRMED / LIKELY / FALSE POSITIVE),
   fix soundness, missed findings, overall recommendation.

How the runner works

run.mts is a self-contained TypeScript runner that:

1. Resolves base ref + merge base + commit list + diff stat.
2. Detects which agent CLIs are available on PATH.
3. For each pass, picks the preferred backend per the fallback order (or skips with a documented note).
4. Writes per-pass prompts to a temp dir and runs the agent non-interactively.
5. Folds outputs into the final report.

The prompts live in the runner: single source of truth so the pipeline and the prompts can't drift apart.