code-review

Define and track response time expectations:

• First response: < 24 hours (business days) for regular PRs
• Urgent PRs: < 2 hours (clearly marked as urgent with justification)
• Merge timeline:
  • Small PRs (< 200 lines): < 2 days
  • Medium PRs (200-400 lines): < 5 days
  • Large PRs (> 400 lines): < 10 days or request split

Fast cycles correlate with healthier delivery metrics.

Size Policies

Enforce PR size limits:

• Target: < 300-500 lines changed
• Hard limit: > 800 lines requires explicit justification
• Exceptions: Refactors, generated code, dependency updates (explain in description)
• Use /code-review-prep to check PR size before opening

CODEOWNERS

Implement automatic reviewer assignment:

• Define ownership boundaries in .github/CODEOWNERS
• Route reviews to domain experts
• Avoid bystander apathy (clear responsibility)
• Use /code-review-init to generate CODEOWNERS template

Suggested Changes

Enable "suggested changes" feature:

• Reviewers offer ready-to-apply edits
• Authors apply with one click or convert to discussion
• Reduces back-and-forth for simple fixes
• Batch multiple suggestions together

Automate the Noise

Move mechanical checks to CI:

• Pre-commit hooks for formatting
• CI checks for tests/lint/types
• Secret scanning and SAST
• Dependency vulnerability scanning

Keep human attention for design and correctness.

Checklists

Author Pre-PR Checklist

Use /code-review-prep to run automated version, or manually verify:

Code Quality

• All tests pass locally
• No linting errors
• TypeScript compiles with no errors
• No debug code (console.log, debugger, TODO unless tracked)

Self-Review

• Reviewed own diff line-by-line
• All changes are intentional and necessary
• No unrelated changes included
• Commit messages are clear

Testing

• Added tests for new functionality
• Updated tests for changed functionality
• Tested edge cases and error scenarios
• Manual testing completed

Documentation

• Updated README if needed
• Added JSDoc for public APIs
• Updated architecture docs if significant changes

Security & Performance

• No hardcoded secrets or API keys
• Input validation where needed
• Performance impact considered
• Ran /review-security if touching auth/permissions

PR Description

• Context explains why
• Changes summarize what
• Test plan enables verification
• Deployment notes identify risks
• Rollback plan documented

Size & Scope

• PR < 400 lines or justified
• Single, clear purpose
• Large refactors split into phases

Reviewer Checklist

Pass 1: High-Level (5-10 min)

• Read PR description, understand context
• Verify change solves stated problem
• Check approach is sound
• No architectural concerns
• Security check (use /review-security if needed)
• Scope is focused and size reasonable

Pass 2: Implementation (10-20 min)

• Logic correct, handles edge cases
• Error handling appropriate
• Tests cover functionality (use /review-testing)
• Code quality good (use /review-quality)
• Naming clear (use /review-readability)
• Documentation adequate

Final Decision

• Classified all comments ([critical], [issue], [suggestion], [nit], [question])
• Left at least one [praise] comment if applicable
• Decision: Approve / Request Changes / Comment

Anti-Patterns to Avoid

# Author workflow
git add .
/review-orchestrator add          # Pre-commit check
git commit -m "feat: add feature"
/code-review-prep                 # Pre-PR checklist
# Open PR with generated description

# Reviewer workflow
/review-security path/to/files    # If security-sensitive
/review-quality path/to/files     # Logic and types
/review-testing path/to/files     # Test quality
# Leave classified comments, make decision

# After completing feature work
git add .
git commit -m "feat: add user profile editing"

# Run pre-PR validation
@skill code-review
> I'm about to open a PR. Can you run the author checklist?

# Claude runs automated checks and generates:
# - Validation results (tests, lint, types)
# - PR size analysis
# - Generated PR description template
# - Suggested reviewers from CODEOWNERS
# - Readiness assessment

# Assigned to review PR #456 (324 lines, auth changes)

@skill code-review
> I need to review PR #456. It modifies authentication. Let's do Pass 1.

# Claude guides through high-level review:
# - Analyzes context and approach
# - Runs `/review-security` for auth changes
# - Identifies any design issues
# - Recommends proceed to Pass 2 or provide feedback

# If Pass 1 looks good:
> Pass 1 looks good. Let's do Pass 2.

# Claude runs specialist reviewers in parallel:
# - `/review-quality` for logic and types
# - `/review-testing` for test coverage
# - `/review-readability` for code clarity
# - Aggregates findings with severity classification

@skill code-review
> We want to improve our code review process. Help us get started.

# Claude runs `/code-review-init`:
# - Generates .github/pull_request_template.md
# - Generates .github/CODEOWNERS
# - Creates docs/code-review-playbook.md
# - Provides team adoption roadmap
# - Suggests SLAs and policies