Code Review

This skill specifies how to review the code on a feature branch.

When to Use This Skill

• When requested
• After making extensive changes, adding new modules or features

Principles

Goals of the Code Review

• Catch bugs and edge cases
• Prevent unnecessary complexity
• Prevent unnecessary dependencies
• Solve the right problem at hand
• Ensure maintainability and readability
• Enforce standards
• Ensure the code is as simple as possible
• Reduce verbosity
• Remove spurious, overly verbose or redundant comments

Anti-Goals

• Unnecessary nitpicking, or pushing personal preferences
• Block progress
• Nitpick formatting (use linters)
• Demand 100% test coverage. We must be measured.
• Commenting everything

Key Questions

• Does the behavior of functions, types and modules match their documentation?
• Does the code reinvent the wheel, problems solved elsewhere?
• Does the change introduce any heavy dependencies?
• Is the code as simple as possible?
• Is the code easy to understand, and is the behavior obvious?
• Are comments helpful, or do they just add clutter?
• Do comments explain the why rather than the what?

Effective Feedback

• Specific
• Brief
• Targeted

Review Scope

• Logic and correctness
• Security and privacy
• Edge case coverage
• Performance implications
• Error handling
• Documentation and comments
• API design and naming
• Architectural fit
• Test quality and correctness
• Quality and focus of comments

Out of Scope

• Running tests
• Running the build
• Running presubmits

Instructions

Phase 1: Gather Code and Context

1. Run ${CLAUDE_PLUGIN_ROOT}/scripts/diff.sh to get lines under review. If the user specified commits or ranges, pass them as arguments.
2. Read commit messages.
3. Run ${CLAUDE_PLUGIN_ROOT}/scripts/comments.sh list to check for existing unresolved PR comments. Human comments require careful attention; bot comments (Copilot, etc.) are lower priority but may highlight real issues.
4. Summarize the changes in 1-3 sentences. Define the problem.

Phase 2: High-level Review

1. Architecture & Design: Does the solution fit the problem? Does the design fit established architecture?
2. Performance Assessment: Are there performance concerns? Is the code efficient?
3. File organization: Are new files in the right places?
4. Testing strategy: Is the test strategy adequate?

Phase 3: Code Review Each Function

1. Logic correctness: Edge cases, off by one, null checks, race conditions.
2. Security: Input validation, injection risks, sensitive data.
3. Performance: Unnecessary loops, suboptimal algorithms.
4. Maintainability: Is the code as simple as can be, is it readable and is the behavior obvious?

Phase 4: Summary

1. Summarize key concerns
2. Propose concrete changes
3. Express level of confidence in each finding, and don't report lower than moderate confidence.
4. If there are unresolved PR comments, note which ones are valid concerns vs. which can be resolved without action.

Phase 5: Resolve Comments

After discussing findings with the user and addressing any valid concerns:

1. Use ${CLAUDE_PLUGIN_ROOT}/scripts/comments.sh resolve --bot to resolve bot comments.
2. For human comments, confirm with the user before resolving, then use comments.sh resolve --human or resolve individually as appropriate.

Review Techniques

Checklists

Use checklists for consistency and thoroughness. Use Security Checklist and others.

Utility Scripts

• diff.sh - Show diff of code under review.
  • No args: diffs current branch against master
  • Single commit (e.g., abc123): shows that commit's changes
  • Range (e.g., abc123..def456): shows changes in that range
  • Multiple args: processes each in sequence
• lint.sh - Run some fast automated checks.
• comments.sh - Manage PR review comments.
  • comments.sh list [PR]: List unresolved comments (human comments first)
  • comments.sh count [PR]: Count comments (human:N bot:N total:N)
  • comments.sh resolve [PR] [--bot|--human]: Resolve comments
  • Human comments are shown with higher priority than bot comments
  • If PR number is omitted, auto-detects from current branch