review

What this skill does

# Code Review Command

Run comprehensive code review on specified files or staged changes.

## Instructions

### Pre-Flight: Research Phase + File Count (MANDATORY)

**CRITICAL: The code-reviewer agent runs a MANDATORY Research Phase (Step 0) before analysis:**

1. **Technology Detection** - Agent scans file extensions, imports, and package manifests
2. **MCP Research** - Agent queries MCP servers for current best practices
3. **Build Truth Context** - Agent builds validated context before reviewing code

This research phase ensures ALL findings are validated against current documentation, not stale training data.

**Before invoking agents, count files to ensure accurate reporting and determine review mode:**

```bash
# For staged changes
FILE_COUNT=$(git diff --staged --name-only | wc -l)

# For PR changes
FILE_COUNT=$(git diff --name-only main...HEAD | wc -l)

# For specific paths - use Glob and count results
```

**Report this count and apply thresholds:**

- **1-49 files**: Standard single-agent review (unless `--consensus` specified)
- **50+ files**: Auto-enable consensus mode (unless `--no-consensus` specified)
- **100+ files**: Warn user and suggest breaking into smaller chunks

**Use the code-reviewer agent to perform systematic code quality analysis.**

The code-reviewer agent provides:

- **Tiered progressive disclosure** for token optimization
- **Security analysis** (OWASP top 10, secrets detection)
- **Performance review** (N+1 queries, resource leaks)
- **Code quality** (SOLID, DRY, clean code principles)
- **CLAUDE.md compliance** for Claude Code ecosystem files
- **Severity levels** (CRITICAL/MAJOR/MINOR)
- **MCP validation** for current best practices and version accuracy (perplexity, context7, microsoft-learn)

**Invoke the agent based on the arguments provided:**

```text
$ARGUMENTS

Based on the arguments, determine the review scope:

If 'staged' or no arguments:
  - Review currently staged files (git diff --staged)
  - Good for pre-commit review

If 'pr' or 'pull-request':
  - Review all changes in the current PR/branch vs main
  - Good for PR review

If specific file paths provided:
  - Review those specific files
  - Can be globs like "src/**/*.ts"

If '--parallel':
  - Run multiple code-reviewer agents in parallel (one per file/module)
  - Good for large changesets
  - ⚠️ CAUTION: Limit to 2-3 Opus agents at a time to prevent context exhaustion

If '--sequential':
  - Run single code-reviewer agent reviewing all files
  - Good for smaller changesets or when context between files matters

If '--batched':
  - Run agents in batches of 2-3, waiting for completion between batches
  - Good for very large changesets (50+ files) or multi-type audits
  - Prevents context exhaustion on large workloads

If '--consensus':
  - Force multi-agent consensus mode (even for small changesets)
  - Launches 3 specialized agents: code-reviewer, security-reviewer, quality-reviewer
  - Consolidates findings based on agreement level
  - Good for critical code paths requiring extra validation

If '--no-consensus':
  - Disable auto-consensus mode (even for 50+ files)
  - Forces single code-reviewer agent
  - Good when you want faster review over higher accuracy

If '--show-rules':
  - Display active rules without running review
  - Shows: config source, tech stack, excluded rules, severity overrides, custom checks
  - Good for verifying configuration before review

If '--ignore-repo-config':
  - Skip .claude/code-review.md and CLAUDE.md configuration
  - Use default rules only (Tier 1 universal checks)
  - Good for comparing with/without repo-specific rules

If '--baseline <branch>' (e.g., '--baseline main', '--baseline develop'):
  - Compare changes against specified branch to identify NEW vs PRE-EXISTING issues
  - Run `git diff <baseline>...HEAD` to get changed line ranges
  - Tag each finding as "new" (line added/modified in this changeset) or "pre-existing"
  - Output separates new issues (prominent) from pre-existing debt (collapsed)
  - Default baseline: 'main' when 'pr' scope is used, none for 'staged'
  - GAME CHANGER for adoption: Teams only see issues THEY introduced, not inherited debt
  - Quality gates (--fail-on-new-critical) apply only to NEW issues

If '--profile <name>':
  - Run focused review using predefined check subsets
  - Profiles:
    - security: OWASP, secrets, auth checks only (fast security scan)
    - quick: Style, obvious issues only (pre-commit fast check)
    - thorough: All checks (default - full review)
    - performance: N+1, complexity, memory, concurrency checks
    - strict: thorough + pattern compliance, module boundaries, dependency migration
  - Good for focused reviews or faster pre-commit checks
  - See SKILL.md profiles section for tier mappings

If '--profile strict':
  - Runs all 'thorough' checks PLUS additional strictness:
    - Pattern compliance: architectural patterns, DI patterns, naming conventions
    - Import hygiene: module boundary violations, barrel file pollution
    - Test correlation: orphaned tests detection
    - Dependency safety: migration verification for major version bumps
  - Higher token cost (~17,000 tokens) but catches more subtle issues
  - Good for critical codebases, library releases, or comprehensive audits

If '--history':
  - Force git history analysis even for profiles that skip it (e.g., quick)
  - Analyzes:
    - Coupling: Files that typically change together
    - Hot spots: High-churn files that need extra scrutiny
    - Author context: Ownership patterns and bus factor
    - Recent patterns: Bug fix history indicating fragile areas
  - Good for investigating unfamiliar code areas or deep reviews
  - Adds ~1,500 tokens for history context analysis

If '--no-history':
  - Skip git history analysis even for profiles that include it (thorough, strict)
  - Saves time when history context isn't needed
  - Good for quick reviews of isolated, well-understood changes
  - Saves ~1,500 tokens

Default: staged changes, sequential mode, auto-consensus for 50+ files, history per profile
```

### Repository Configuration

The review command automatically loads repository-specific rules from:

1. **`.claude/code-review.md`** (primary) - Dedicated config file in .claude folder
2. **CLAUDE.md + @imports** (fallback) - Extracts rules from existing project instructions

**Configuration Priority Chain:**

```text
1. .claude/code-review.md exists?
   └── Yes: Parse config, apply rules
   └── No: Continue to fallback

2. CLAUDE.md exists?
   └── Yes: Read + follow @imports, extract rules
   └── No: Continue to defaults

3. No config found (interactive mode):
   └── AskUserQuestion: "No review configuration found. Review with default rules?"
   └── User can confirm or provide guidance
```

**What Gets Configured:**

| Section | Effect |
| --- | --- |
| `## Tech Stack` | Override auto-detected tech, improve MCP query accuracy |
| `## Exclude Rules` | Skip specific rules (e.g., `sql-injection` for non-DB projects) |
| `## Severity Overrides` | Change default severity (CRITICAL→MAJOR, MAJOR→MINOR) |
| `## Custom Checks` | Add project-specific validation (file patterns, content rules) |

See [repo-config.md](../skills/code-reviewing/references/tier-4/repo-config.md) for full schema documentation.

## Claude Code Component Validation (MANDATORY)

**CRITICAL: When Claude Code files are detected in the review scope, specialized validation via auditor agents is MANDATORY. This is NOT optional - if validation cannot run, the review FAILS.**

Claude Code components (skills, agents, commands, hooks, memory files, plugins, etc.) require validation against official documentation via the `docs-management` skill. The code-reviewer agent performs only basic syntax checks - comprehensive validation requires specialized auditor agents.

### Why Auditors Are Required

The code-reviewer agent:

- Lacks `Task` tool access (cannot spawn subagents)
- Can only perform basic syntax validation (YAML/JSON structure)
-