Code Review

Code Review

This skill specifies how to review the code on a local feature branch or a range of commits. Optionally can take into account PR comments.

When to Use This Skill

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

Instructions

Follow these steps exactly:

Phase 1: Gather 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. Launch a sonnet agent to view the diff and commit messages and generate a summary of changes.
3. Launch a haiku agent to collect existing unresolved PR comments, if any. The agent should run ${CLAUDE_PLUGIN_ROOT}/scripts/comments.sh list.
4. Launch a haiku agent to collect a list of applicable CLAUDE.md files, which share a path with any files under review.

Phase 2: Review

Launch 5 agents in parallel to independently review the changes. Each agent should return a list of issues, with each issue including a description, the reason it was flagged and confidence. The agents should do the following:

Agent 1: Sonnet CLAUDE.md compliance agent Audit changes for CLAUDE.md compliance. Only consider CLAUDE.md files that share a path with the file under review.

Agent 2: Opus bug agent Scan for bugs. Focus only on the diff itself without reading extra context. Flag only significant bugs; ignore nitpicks and likely false positives. Do not flag issues that you cannot validate without looking at content outside of the git diff.

Agent 3: Opus bug agent Look for problems that exist in the introduced code. Include security issues, incorrect logic, etc. Only look for issues that are related to the changed code. Consult non-exhaustive checklists in reference/, but do not be limited by them.

Agent 4: Opus architecture & style agent Look for deviations from the project architecture and style. Primary concerns: (1) file organization (2) testing strategy (3) architecture and design (4) maintainability. Agent should flag code that is overly complex, explanations that are too verbose, tests that are redundant. The threshold for confidence is high: do not flag issues that are subjective or uncertain.

Agent 5: Opus performance optimizer Look for opportunities to optimize the code. Focus on the performance checklist in reference/

Important: We only want high-signal issues. This means:

• 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

We specifically do not want:

• Unnecessary nitpicking, or pushing personal preferences
• Block progress
• Nitpick formatting (use linters)
• Demand 100% test coverage. We must be measured.
• Adding comments and docstrings on everything
• Potential issues that "might" become problems

In addition to the above, each subagent should be told the change summary to communicate author intent and important context.

Phase 3: Double-check and consider comments

For each issue found in the previous phase, launch parallel subagents to validate the issue. These subagents should get the change summary and a description of the issue. The agent's job is to review the issue and validate that the stated issue is real and significant. For example, if an issue such as "variable is not defined", then the subagent's job would be to validate that is actually true in the code.

For each comment on the PR, launch parallel subagents to investigate. Assign high confidence to human comments and low confidence to bot comments. The agent's job is to review the issues and validate that it's real and significant.

Use Opus agents for bugs, logic issues and PR comments and Sonnet agents for CLAUDE.md violations.

Phase 4: Filter

Filter out any issues that were not validated in phase 3. This will give us the final list of high-signal issues for review.

Phase 5: Present findings

Present the user with a summary. For each issue include:

• path: The file path
• lines: The buggy line or lines so the the user sees them
• body: Description of the issue. For small fixes, include a suggestion with corrected code.

Phase 6: Resolve Comments, if any

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

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 is:

• Specific
• Brief
• Targeted

Checklists

Use non-exhaustive checklists for consistency and thoroughness. They include:

• Security Checklist
• Common Bugs
• Comments Checklist
• Performance Issues

Important: The checklists are not complete. They point out common issues, but are not a replacement for a thorough review.

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.