code-review

---
name: code-review
description: Multi-persona code review with Architect and Nitpicker perspectives
---

# Code Review

## Trigger Phrases

- "code review"
- "review this branch"
- "review my code"
- "review my changes"

## Inputs

No input required. The skill reviews the current branch's changes against the base branch.

Optional inputs:
- A specific base branch: "review my code against develop"
- A file filter: "review just the test files"
- A focus area: "review with focus on naming" or "review the architecture"

## Workflow

### Step 1: Gather the Diff

Using local git commands:

1. Identify the current branch name: `git branch --show-current`
2. Identify the base branch (default: `main`): check if `main` exists, fall back to `master`
3. Get the full diff: `git diff [base]...HEAD`
4. List changed files: `git diff --name-only [base]...HEAD`
5. Get a stat summary: `git diff --stat [base]...HEAD`

If there are no changes, tell the user: "No changes found against [base]. Are you on the right branch?"

If the diff is very large (50+ files or 2000+ lines changed), warn the user and offer to review a subset (e.g., by directory or file type).

### Step 2: Run Reviews in Parallel

Run two review perspectives simultaneously. Each persona is defined in a shared file — read the persona definition before starting the review.

#### Architect Review

Read `shared/personas/architect.md` for the full persona definition.

Focus areas:
- **Pattern Consistency**: Does the code follow established patterns in the codebase?
- **Reusability**: Is there existing code that should be reused?
- **Simplification**: Is there a simpler approach?
- **Abstraction Level**: Right level of abstraction for the use case?
- **Responsibility**: Single responsibility per function/class?
- **Dependency Injection**: Dependencies injectable and testable?
- **Dependency Direction**: Dependencies flowing correctly?
- **API Design**: Public interfaces intuitive and consistent?

Review the diff and identify issues. For each issue:
- Prefix with `Arch:`
- Tag the focus area: `[PatternConsistency]`, `[Reusability]`, etc.
- Rate importance: High, Medium, or Low
- Include a specific suggestion or question

#### Nitpicker Review

Read `shared/personas/nitpicker.md` for the full persona definition.

Focus areas:
- **Naming**: Precise, intention-revealing, consistent names?
- **Boolean Naming**: Booleans read as yes/no questions?
- **Test Naming**: Test names describe scenario and outcome?
- **Comment Quality**: Comments explain why, not what?
- **Magic Values**: No unexplained literals?
- **Dead Code**: No commented-out code, stale TODOs, debug statements?
- **Consistent Patterns**: Similar operations follow similar patterns?
- **Variable Clustering**: Related variables grouped together?

Review the diff and identify issues. For each issue:
- Prefix with `Nit:`
- Tag the focus area: `[Naming]`, `[MagicValues]`, etc.
- Rate importance: High, Medium, or Low
- Include a concrete fix suggestion

### Step 3: Merge and Deduplicate

Combine findings from both perspectives.

- Remove duplicates (same issue flagged by both personas — keep the more detailed one)
- Sort by importance: High first, then Medium, then Low
- Group by file for readability

### Step 4: Write the Review Report

Present findings in this format:

```
## Code Review: [branch-name]
**Files changed**: [count] | **Lines**: +[added] / -[removed]

### High Priority
[Issues that should be addressed before merging]

### Medium Priority
[Issues worth addressing but not blocking]

### Low Priority
[Polish items — address if time permits]

### Summary
[2-3 sentence overview: what's good about the changes, what needs attention]
```

Rules for the report:
- Lead with what's good. Acknowledge solid work before listing issues
- Every issue must have a concrete suggestion, not just criticism
- If there are no High issues, say so explicitly — that's a good sign
- Cap the report at 15 issues. If there are more, prioritize and note "additional minor items omitted"

### Step 5: Offer Next Steps

After presenting the review, offer:
- "Want me to fix any of these?" (for auto-fixable issues like naming, magic values)
- "Want me to focus on a specific file or area?"

## Notes

- This skill uses local git commands only. It does not interact with any git hosting platform
- The skill reviews code, not commits. It looks at the total diff, not individual commit messages
- For large diffs, suggest reviewing in chunks rather than skipping the review entirely
- If persona files (`shared/personas/architect.md`, `shared/personas/nitpicker.md`) are not found, use the focus areas listed in Step 2 as the review criteria
- If the user asks to focus on just one perspective ("review the architecture only"), run only that persona

## Examples

**User**: "code review"
**Action**: Diff current branch against main. Run Architect and Nitpicker reviews in parallel. Present merged findings sorted by priority.

**User**: "review my code against develop"
**Action**: Same flow, but diff against `develop` instead of `main`.

**User**: "review just the test files"
**Action**: Filter the diff to only `*.test.*` and `*.spec.*` files. Run both reviews on the filtered set. Nitpicker's TestNaming focus becomes especially relevant.

**User**: "review with focus on architecture"
**Action**: Run only the Architect perspective. Skip Nitpicker. Present findings focused on patterns, abstractions, and dependencies.