/review-branch

description: "Review an existing branch holistically before merging — blast radius, conventions, security, and spec compliance"
allowed-tools: ["Read(*)", "Bash(*)", "Grep(*)", "Glob(*)", "Agent(forge:forge-reviewer,forge:forge-verifier,forge:forge-researcher)", "WebSearch(*)", "WebFetch(*)"]

Forge Review Branch

Review an unmerged branch holistically. Dispatches parallel review agents that examine the total diff (not commit-by-commit), check blast radius, verify conventions, and validate security — following Anthropic's multi-agent review architecture.

Usage

/forge review-branch [FLAGS]

Parse Arguments

| Flag | Default | Description | |------|---------|-------------| | `--base BRANCH` | `main` | Base branch to diff against | | `--head BRANCH` | current HEAD | Branch to review (defaults to current branch) | | `--spec SPEC` | *(none)* | Path to spec file for acceptance criteria verification | | `--depth quick\|standard\|thorough` | `standard` | Review depth | | `--fix` | *(off)* | Automatically fix CRITICAL issues found | | `--comment` | *(off)* | Post results as GitHub PR comment via `gh` |

Pre-flight Check

1. Verify this is a git repository. If not: `Not a git repository.` 2. Verify the base branch exists: `git rev-parse --verify {base}`. If not: `Base branch '{base}' not found.` 3. Verify there are changes to review: `git diff --name-only {base}...{head}`. If empty: `No changes between {base} and {head}. Nothing to review.` 4. Read `.forge/capabilities.json` if it exists (for tool-aware review).

Step 1: Gather Branch Context

Run these commands to understand the full scope of changes:

# Total diff stats
git diff --stat {base}...{head}

# All changed files
git diff --name-only {base}...{head}

# Commit log for the branch
git log --oneline {base}...{head}

# Number of commits
git rev-list --count {base}...{head}

Present a brief summary:

Forge Review Branch
===================================
Base:    {base}
Head:    {head}
Commits: {N}
Files:   {M} changed ({additions}+, {deletions}-)

Step 2: Convention Inference

Before reviewing, understand the codebase's conventions (same as forge-executor Step 4):

1. Check for CLAUDE.md, .editorconfig, linting config 2. If absent, auto-detect from existing code:

• Import style (ESM vs CJS)
• Naming conventions
• Error handling patterns
• Test framework and location
• File organization

3. Store inferred conventions for use by review agents

Step 3: Dispatch Parallel Review Agents

Following Anthropic's multi-agent review pattern, dispatch these agents in parallel:

Agent 1: Spec Compliance Reviewer (if --spec provided)

Dispatch **forge-reviewer** with:

• The spec file's R-numbered requirements and acceptance criteria
• The full list of changed files
• Task: verify every acceptance criterion is met by the branch's changes

Agent 2: Blast Radius Analyzer

For each changed file that exports functions/classes/types: 1. Find all files in the codebase that import from it: `grep -r "from.*{file}" src/` 2. Check if exported signatures changed (parameters, return types, removed exports) 3. For each dependent: check if it handles the change correctly 4. Flag breaking changes as CRITICAL, untested dependents as IMPORTANT

Output:

BLAST RADIUS:
- {file}: {N} dependents
  - {dependent}: uses {export} — SAFE|BREAKING|NEEDS_TEST
- Total breaking changes: {N}
- Untested dependents: {N}

Agent 3: Convention & Quality Reviewer

Dispatch **forge-reviewer** in code quality mode:

• Check all changed files against inferred conventions
• Flag style inconsistencies with the existing codebase
• Check for security issues (OWASP top 10 patterns)
• Check for stubs, TODOs, placeholder code
• Check test quality (specific assertions, not toBeTruthy)

Agent 4: Research Validator (thorough depth only)

Dispatch **forge-researcher** to verify:

• Are security-sensitive patterns (auth, crypto, input validation) following best practices?
• Are framework patterns matching official documentation?
• Are there known vulnerabilities in approaches used?

Step 4: Verification Pass

After parallel agents complete, run verification checks:

1. **Aggregate findings** — collect all issues from all agents 2. **Deduplicate** — same issue flagged by multiple agents counts once 3. **Validate each finding** (Anthropic's verification pattern):

• For each CRITICAL or IMPORTANT finding, re-read the actual code at the flagged location
• Attempt to disprove the finding — is there context that makes it correct?
• Only retain findings with confidence >= 80%

4. **Run affected tests** (if test runner available):

   # JavaScript
   npx jest --changedSince={base} --passWithNoTests
   # Python
   python -m pytest --co -q  # collect affected tests

Step 4.5: Transcript Cross-Check (T008 / R014)

If `.forge/history/cycles/<cycle-id>/transcript.jsonl` exists for any cycle that touched this branch, cross-check agent claims against reality. A transcript line is written by the stop-hook on every iteration and by the forge-executor on every task completion, so the file is the ground truth for what agents *said* they did.

1. **Locate transcripts**. List every `transcript.jsonl` under `.forge/history/cycles/` whose newest line is more recent than `git log {base}...{head} --pretty=%ci | tail -1` minus a 5-minute buffer. These are the cycles that can have produced the commits under review.

2. **Load the transcript**. Use the library (same file both entries and boundary lines get you):

   node -e "console.log(JSON.stringify(require('./scripts/forge-tools.cjs').readTranscript('.forge','<cycle-id>'), null, 2))"

3. **Cross-check A — every reviewed task has ≥ 1 transcript entry.** For every task id that appears in the branch commits (`git log {base}...{head} --pretty=%s | grep -oE 'T[0-9]+'`), verify there is at least one transcript entry with `task_id` equal to that id.