/craft-review

name: review
description: "PR review skill - invokes pr-reviewer-expert agent against branch diff, story commits, or full project audit."

Review

Run a PR-style code review using the crystallized pr-reviewer-expert agent. Three approaches based on what you want reviewed.

Modes

| Mode | Trigger | What gets reviewed | |------|---------|-------------------| | **Branch** (default) | `/craft:review` | Everything on current branch not on origin/main | | **Story** | `/craft:review story [name]` | Commits from a specific story | | **Project** | `/craft:review project [path]` | Full codebase or subsystem audit (no diffs) |

Optional focus flag: `--focus security|consistency|performance|correctness` (default: correctness + security)

Optional review strategy: `--maze` enables perpendicular maze review (architect generates questions, runner answers them). Without `--maze`, uses the existing single-agent generalist review.

Flow

Step 1: Determine Mode and Scope

**Parse args to determine review scope:**

• No args or `branch` → **Branch mode**
• `story` or `story <name>` → **Story mode**
• `project` or `project <path>` → **Project mode**

Extract `--focus` flag if present. Default focus is `correctness,security`.

Step 2: Gather Context

**Always pre-load these files (read them, include relevant content in agent prompt):**

1. `.craft/design/locked.md` - locked decisions the reviewer must respect 2. `.craft/project.md` - stack, patterns, conventions 3. `.craft/quality.yaml` - quality gates

Step 3: Gather Diff / Scope

**Branch mode:**

# Detect the default remote branch
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")

# Get the diff
git diff origin/${DEFAULT_BRANCH}...HEAD

# Get changed file list
git diff --name-only origin/${DEFAULT_BRANCH}...HEAD

# Get commit log for the branch
git log --oneline origin/${DEFAULT_BRANCH}..HEAD

If there are no commits ahead of origin, tell the user:

> "No commits ahead of origin/${DEFAULT_BRANCH}. Nothing to review."

**If diff exceeds ~500 lines**, split by directory or subsystem. Run the agent multiple times with scoped diffs rather than one massive prompt. Tell the user:

> "Large diff ([N] lines across [M] files). I'll review in batches by directory to keep findings sharp."

**Story mode:**

If no story name provided, check `.craft/.global-state` for CURRENT_STORY. If none active, use AskUserQuestion to pick from completed/active stories in the current cycle.

# Read story file to find associated commits
# Look for commits that reference the story name
git log --oneline --all --grep="[story-name]"

# If no story-tagged commits found, ask user for commit range

Get cumulative diff across those commits. Also read the story file itself so the agent knows intent.

**Project mode:**

No diff. Instead gather:

• Directory tree of relevant source files
• If a path was specified, scope to that subtree
• The agent will do full file reads during its review

Step 4: Route - Standard or Maze

Check if `--maze` flag is present. If not, go to **Step 4a (Standard)**. If yes, go to **Step 4b (Maze)**.

---

Step 4a: Standard Review (no --maze)

**INVOKE the pr-reviewer-expert agent using the Agent tool.**

Build the prompt with:

1. **Mode** - what kind of review this is 2. **Context** - locked.md content, project.md content, quality.yaml content 3. **Diff** - the actual diff (branch/story modes) or file list (project mode) 4. **Changed files** - list of files that changed (branch/story modes) 5. **Commit messages** - so the agent understands intent 6. **Focus** - which lens to prioritize 7. **Story intent** - the story file content (story mode only)

**Prompt structure for the agent:**

You are reviewing code for [project name].

PLUGIN_ROOT: ${CLAUDE_PLUGIN_ROOT}
(The agent cannot resolve this variable itself - this line passes the resolved path.)

## Mode: [Branch|Story|Project]

## Focus: [correctness, security, ...]

## Project Context
[locked.md content]
[project.md relevant sections]
[quality.yaml content]

## [Diff / File List]
[the actual diff or file list]

## Changed Files
[list of changed files - read each one fully for surrounding context]

## Commit Messages
[commit log]

## Instructions
- Read each changed file in full (not just the diff) to understand surrounding context
- Check imports/callers of changed functions for cross-file issues
- Respect locked decisions - do not flag patterns that are explicitly locked
- Use two severity levels: issue (must fix) and suggestion (consider)
- [For project mode: add "pattern" severity for consistency observations]
- Categorize each finding: security, logic, performance, consistency, or doc-drift
- doc-drift = stale references in docs/comments, terminology that doesn't match current code, outdated examples, references to renamed/removed symbols
- Lead with the finding, include file:line and category, provide a fix diff
- Focus on: [focus areas]
- Do NOT comment on formatting/style if linters exist
- If the diff is clean and you have no real findings, say so - do not manufacture issues

Then skip to **Step 5: Present Findings**.

---

Step 4b: Maze Review (--maze)

The maze review splits question-generation from question-answering. The architect decides WHAT to investigate. The runner investigates it. This prevents the infinite-regression problem where fixing 10 issues reveals 10 more.

Step 4b.1: Slice the Diff (if needed)

If the diff exceeds ~500 lines, slice it by subsystem/directory:

# Get changed files grouped by top-level directory
git diff --name-only origin/${DEFAULT_BRANCH}...HEAD | sed 's|/.*||' | sort -u

Create one slice per subsystem. Each slice gets its own architect pass. Tell the user:

> "Large diff ([N] lines). Slicing into [M] subsystems for maze review."

For diffs under 500 lines, use the entire diff as a single slice.

Step 4b.2: