Review Template

Code Review Template

This skill defines the output format, severity levels, and quality bar for code reviews.

Output Format

Reviews are saved to: .claude/agent-outputs/reviews/<YYYY-MM-DDTHHmmssZ>-<scope>-review.md

Document Structure

## Summary

**Scope**: [Files/modules reviewed]
**Verdict**: [APPROVE | NEEDS CHANGES | REJECT]
**Key Finding**: [One sentence - the most important thing the author needs to know]

## Critical Issues

[Issues that MUST be fixed before merge. Empty section = none found.]

### Issue 1: [Descriptive Title]

**Location**: `file.py:42`
**Problem**: [What's wrong - specific and factual]
**Impact**: [Why it matters - security, correctness, data loss, etc.]
**Fix**: [Concrete suggestion]

## Improvements

[Issues that SHOULD be addressed. Grouped by category.]

### Organization
- `file.py:15` - [Issue and suggestion]

### Design
- `file.py:30` - [Issue and suggestion]

## Nitpicks

[Minor style/preference items. Keep brief - one line each.]

- `file.py:10` - [Issue]
- `file.py:25` - [Issue]

## Questions

[Clarifications needed before approval. Don't use for rhetorical questions.]

1. [Specific question about intent or requirements]

Severity Definitions

Critical Issue Examples

• SQL injection, XSS, command injection
• Race conditions causing data corruption
• Unhandled exceptions that crash the app
• Logic errors producing wrong results
• Missing authentication/authorization checks

NOT Critical (even if bad)

• Missing docstrings
• Inconsistent naming
• Suboptimal performance (unless severe)
• Code duplication
• Missing type hints

Verdict Criteria

Writing Guidelines

Be Specific

# INCORRECT - vague
The error handling could be better.

# CORRECT - specific
`file.py:42` - Bare `except:` catches KeyboardInterrupt and SystemExit.
Catch specific exceptions: `except (ValueError, KeyError):`.

Be Concise

# INCORRECT - verbose
I noticed that on line 42, there appears to be an issue where the function
is not properly validating its input parameters before proceeding with the
main logic, which could potentially lead to unexpected behavior if invalid
data is passed in by the caller.

# CORRECT - direct
`file.py:42` - No input validation. Add: `if not data: raise ValueError("data required")`

Explain Impact, Not Just Rules

# INCORRECT - rule citation
This violates PEP 8 naming conventions.

# CORRECT - explains why it matters
`user_ID` mixes snake_case with uppercase. Inconsistent naming makes
code harder to search and remember. Use `user_id`.

Skip Empty Sections

If a section has no items, omit it entirely. Don't write "None found" or "N/A".

Prioritize

Don't bury critical issues under 20 nitpicks. Lead with what matters.

Anti-Pattern: Review Inflation

Avoid these behaviors that reduce review value:

Convention References

When flagging convention violations, reference the skill:

**Convention**: See `function-design` skill: Guard Clauses

This lets authors learn the standard, not just the specific fix.