workflows-review

What this skill does

# Review Command

## Runtime Tools

When this skill needs user questions, todo/progress tracking, subagents, or another skill, use the active runtime equivalents in [RUNTIME_TOOLS.md](../RUNTIME_TOOLS.md).


Adhere to the Builder Ethos (ETHOS.md): Boil the Lake, Search Before Building, User Sovereignty.

Perform exhaustive code reviews using multi-agent analysis, dynamic skill/agent discovery, and optional prd.json integration.

## Prerequisites

- Git repository with GitHub CLI (`gh`) installed and authenticated
- Clean main/master branch
- Proper permissions to create worktrees and access the repository

## Review Target

<review_target> $ARGUMENTS </review_target>

## Workflow

### 1. Determine Review Target & Setup

**Target Detection:**

| Input | Type | Action |
|-------|------|--------|
| Numeric (e.g., `123`) | PR number | `gh pr view 123 --json` |
| GitHub URL | PR URL | Extract PR number, fetch metadata |
| `docs/plans/*/` path | Plan folder | Review against prd.json stories |
| Branch name | Branch | Checkout or worktree |
| Empty | Current branch | Review current branch changes |

**Setup Tasks:**

- [ ] Detect review target type
- [ ] Check current git branch
- [ ] If on target branch → proceed with analysis
- [ ] If different branch → offer worktree: `git worktree add ../<branch> <branch>` (use absolute paths after)
- [ ] Fetch PR metadata: `gh pr view --json title,body,files,baseRefName`
- [ ] If plan folder provided → read prd.json for story context

### 2. Discover & Launch ALL Review Agents

You MUST discover and run agents. This is not optional. Do not skip agents. Do not rationalize running fewer agents.

**Discover Review Agents:**

```bash
# Core and auxiliary agents by runtime
find ~/.claude/agents -name "*.md" 2>/dev/null
find ~/.codex/agents -name "*.toml" 2>/dev/null
find ~/.config/opencode/agents -name "*.md" 2>/dev/null

# Plugin agents when exposed by the active agent runtime
find ~/.codex/plugins ~/.claude/plugins ~/.config/opencode/plugins -path "*/agents/*" 2>/dev/null
```

**Extract agent metadata:**

```bash
for agent in $(find ~/.claude/agents ~/.codex/agents ~/.config/opencode/agents ~/.codex/plugins ~/.claude/plugins ~/.config/opencode/plugins -path "*/agents/*" 2>/dev/null); do
  name=$(sed -n '/^---$/,/^---$/p' "$agent" | grep "^name:" | cut -d: -f2- | xargs)
  [ -z "$name" ] && name=$(grep '^name = ' "$agent" | cut -d= -f2- | tr -d '" ' | xargs)
  category=$(dirname "$agent" | xargs basename)
  echo "AGENT|$name|$category"
done
```

**Agent sources:**

| Source | Agents | Purpose |
|--------|--------|---------|
| Active runtime user agents | security-sentinel, performance-oracle, architecture-strategist, code-simplicity-reviewer, kieran-typescript-reviewer, pattern-recognition-specialist | Core review |
| Active runtime user agents | design-implementation-reviewer, figma-design-sync | UI review |
| Active runtime user agents | git-history-analyzer | Historical context |
| pr-review-toolkit plugin | code-reviewer, silent-failure-hunter, type-design-analyzer, pr-test-analyzer, comment-analyzer | PR-specific review |
| pr-review-toolkit plugin | code-simplifier | Active code simplification |
| code-review plugin | code-review | Active code review |

**Simplification Agents - Different Roles:**

| Agent | Type | When to Use |
|-------|------|-------------|
| `code-simplicity-reviewer` | Audit | Identifies complexity issues, flags for review |
| `code-simplifier` | Refactor | Actively simplifies code, applies changes |

Use `code-simplicity-reviewer` during review phase, `code-simplifier` after implementation for cleanup.

**Discover Relevant Skills:**

```bash
find ~/.agents/skills -name "SKILL.md" 2>/dev/null
find ~/.codex/plugins ~/.claude/plugins ~/.config/opencode/plugins -path "*/skills/*/SKILL.md" 2>/dev/null
```

**Skill Categories for Reviews:**

| Skill | Use When PR Contains |
|-------|---------------------|
| `vercel-react-best-practices` | React, Next.js components |
| `vercel-composition-patterns` | Component architecture |
| `emil-design-engineering` | UI, forms, accessibility |
| `web-animation-design` | Animations, transitions |
| `web-design-guidelines` | UX, accessibility |
| `stripe-best-practices` | Payment code |

**Core Review Agents (always run):**

- Launch subagent `security-sentinel` with prompt ("Review these changed files for security vulnerabilities: <changed_files>")
- Launch subagent `performance-oracle` with prompt ("Review these changed files for performance issues: <changed_files>")
- Launch subagent `architecture-strategist` with prompt ("Review these changed files for architectural concerns: <changed_files>")
- Launch subagent `code-simplicity-reviewer` with prompt ("Review these changed files for unnecessary complexity: <changed_files>")
- Launch subagent `pattern-recognition-specialist` with prompt ("Review these changed files for anti-patterns: <changed_files>")
- Launch subagent `code-reviewer` with prompt ("Review these changed files for code quality issues: <changed_files>")

Every single one. No exceptions.

**Conditional Agents:**

| Condition | Agent | Source |
|-----------|-------|--------|
| TypeScript files | `kieran-typescript-reviewer` | active runtime user agents |
| UI components | `design-implementation-reviewer` | active runtime user agents |
| New types defined | `type-design-analyzer` | pr-review-toolkit plugin |
| Error handling code | `silent-failure-hunter` | pr-review-toolkit plugin |
| Test files | `pr-test-analyzer` | pr-review-toolkit plugin |
| Comments added | `comment-analyzer` | pr-review-toolkit plugin |
| Plan folder has breadboard | `breadboard-reflection` | skill |

If a conditional agent's trigger exists in the changeset, you MUST launch it. Do not skip.

**Breadboard-Reflection Agent (when plan folder has breadboard):**

Load the `/breadboard-reflection` skill and run these checks against the implementation:
- Trace user stories through implementation code
- Run naming test: can each function be named with one idiomatic verb?
- Check for wiring mismatches: does code call chain match breadboard Wires Out?
- Check for stale affordances: breadboard shows something that doesn't exist in code
- Check for missing affordances: code has paths not in the breadboard

**Research Agent:**

```
Launch subagent `git-history-analyzer`: "Analyze historical context for changed files"
```

### 3. Wait for ALL agents, then proceed

Do NOT move to the next step until every launched agent has returned findings. Collect all results before synthesizing.

### 4. Apply Relevant Skills

**For React/Next.js PRs:**
```
skill: vercel-react-best-practices
skill: vercel-composition-patterns
```

**For UI PRs:**
```
skill: emil-design-engineering
skill: web-animation-design
skill: web-design-guidelines
```

**UI Review Checklist (from emil-design-engineering):**

- [ ] No layout shift on dynamic content
- [ ] Animations have `prefers-reduced-motion` support
- [ ] Touch targets 44px minimum
- [ ] Hover effects use `@media (hover: hover)`
- [ ] Icon buttons have aria labels
- [ ] Inputs 16px+ (prevent iOS zoom)
- [ ] No `transition: all`
- [ ] z-index uses fixed scale

### 5. Stakeholder Perspective Analysis

**Developer Perspective:**
- How easy is this to understand and modify?
- Are the APIs intuitive?
- Is debugging straightforward?
- Can I test this easily?

**Operations Perspective:**
- How do I deploy this safely?
- What metrics and logs are available?
- How do I troubleshoot issues?
- What are the resource requirements?

**End User Perspective:**
- Is the feature intuitive?
- Are error messages helpful?
- Is performance acceptable?
- Does it solve the problem?

**Security Perspective:**
- What's the attack surface?
- Are there compliance requirements?
- How is data protected?
- What are the audit capabilities?

### 6. Scenario Exploration

**Scenario Checklist:**

- [ ] **Happy Path**: Normal operation with valid inputs
- [ ] **Invalid Inputs**: Null, empty, malform