code-review

name	code-review
description	Branch code review with structured scoring against project guidelines. Produces categorized findings with severity levels and LLM-generated fix prompts. Quality gate: only posts review to PR if score meets threshold. Triggers on: "code review", "review branch", "review PR", "review changes", "score code"

/code-review

Structured code review with scoring, findings, and auto-generated fix prompts.

Purpose

Review all changes on a branch (or between two refs) against project coding guidelines. Produce a scored report with categorized findings, severity levels, and actionable fix prompts that an LLM can execute directly. Supports a quality gate: if the score meets the threshold, post the review as a PR comment. If below threshold, return findings to the developer for iteration.

Usage

# Review current branch against main
/code-review

# Review a specific branch
/code-review --branch feature/auth-refactor

# Review with custom threshold
/code-review --branch feature/auth-refactor --gate 9

# Review and post to PR if passing
/code-review --pr 42 --post-if-passing

# Review against specific guidelines
/code-review --guidelines .cursor/rules/elixir.md

# Output as JSON for CI integration
/code-review --format json

Arguments

Flag	Type	Default	Description
--branch	string	current branch	Branch to review
--base	string	main	Base branch to diff against
--pr	int	—	Pull request number to review
--gate	int	8	Minimum score (1-10) to pass quality gate
--post-if-passing	flag	false	Post review as PR comment if score >= gate
--guidelines	string	auto-detect	Path to coding guidelines file
--format	enum	markdown	Output format: markdown, json
--severity	enum	all	Filter findings: all, critical, major, minor
--fix-prompts	flag	true	Generate LLM fix prompts for each finding
--max-files	int	50	Maximum files to review (largest diff first)

Workflow

1. Diff — Compute the full diff between --base and --branch. Identify all changed files, additions, deletions, and modifications.
2. Load guidelines — Read project coding guidelines (from --guidelines, CLAUDE.md, .cursor/rules/, or language-specific defaults). Extract the rules to check against.
3. Categorize changes — Group changed files by type: logic, tests, config, docs, migrations. Prioritize logic and test files for deep review.
4. Review each file — For every changed file, check against guidelines. Look for: correctness, security, performance, maintainability, test coverage, style, naming, error handling.
5. Score — Assign a score from 1-10 based on findings. Deductions: critical (-3), major (-1.5), minor (-0.5). Floor at 1. Start at 10 and subtract.
6. Generate fix prompts — For each finding, produce a self-contained prompt that an LLM can use to fix the issue. Include file path, line range, what's wrong, and what the fix should look like.
7. Gate check — Compare final score against --gate. If passing and --post-if-passing is set, format and post as PR comment.
8. Report — Output the full review with score, findings, fix prompts, and pass/fail status.

Examples

Standard branch review

/code-review --branch feature/user-auth

## Code Review — feature/user-auth

### Score: 7/10 — BELOW GATE (8)

### Findings
| # | Severity | File | Line | Issue |
|---|----------|------|------|-------|
| 1 | CRITICAL | lib/auth/session.ex | 45 | Token stored in plain text without encryption |
| 2 | MAJOR | lib/auth/login.ex | 23 | Missing rate limiting on login endpoint |
| 3 | MAJOR | test/auth_test.exs | — | No tests for token expiration edge case |
| 4 | MINOR | lib/auth/session.ex | 12 | Variable name `t` should be descriptive |

### Fix Prompts
#### Finding #1 — Token encryption
> In `lib/auth/session.ex` line 45, the session token is stored as plain text.
> Encrypt it using `Plug.Crypto.encrypt/3` before storage and decrypt on read.
> Reference: project guideline §Security — "All tokens at rest must be encrypted."

Output

## Code Review — <branch>

### Score: N/10 — PASS | BELOW GATE

### Summary
- Files reviewed: N
- Findings: N critical, N major, N minor
- Guidelines checked: N rules

### Findings
| # | Severity | File | Line | Issue |
|---|----------|------|------|-------|
| 1 | ... | ... | ... | ... |

### Fix Prompts
#### Finding #N — Title
> Actionable LLM prompt to fix the issue...

### Verdict
PASS — Ready to merge | FAIL — Address N findings before merge

Dependencies

• Git (diff between refs)
• Project guidelines file (auto-detected or specified)
• /create-pr — Optional integration for posting reviews
• GitHub CLI (gh) — For PR comment posting