Splitting Reviews

This reference document provides guidance on how to subdivide a large or complex code review into smaller, manageable chunks to maintain high quality and avoid context overload.

When to Split a Review

Consider splitting a review when:

• The diff is large (e.g., > 500 lines or > 10 files).
• The changes span multiple distinct components or layers (e.g., frontend, backend, database).
• The PR contains multiple unrelated features or bug fixes (though ideally these should be separate PRs, sometimes they are combined).
• You notice that your review comments are becoming superficial or missing details in later files.

Strategies for Splitting

1. By File or Component

The most common approach is to review files in logical groups:

• By Directory: Review files folder by folder if the project is well-organized by feature or component.
• By Layer: Review database changes first, then backend logic, then frontend UI, then tests. This helps build context sequentially.
• By File Type: Review core logic files (.ts, .java, .go) separately from configuration files or documentation.

2. By Concern or Perspective

You can also make multiple passes over the same set of changes focusing on different concerns:

• Pass 1: Correctness and Architecture: Focus solely on whether the code does what it is supposed to do and fits the overall design.
• Pass 2: Style and Maintainability: Focus on readability, naming conventions, and adherence to style guides.
• Pass 3: Security and Performance: Focus on potential vulnerabilities and optimization opportunities.

Tooling Support

To assist with splitting large diffs, use the provided Python script: scripts/split_diff.py (inside the directory the SKILL.md is in)

This script can:

• Read a diff from stdin or a file.
• Extract a diff from a JSON file (useful if the diff is wrapped in JSON).
• Split the diff into separate files per changed file in a specified output directory.

Usage Example:

python3 agents/skills/code-review/scripts/split_diff.py --output-dir scratch/diff_chunks < diff.txt

For JSON inputs:

python3 agents/skills/code-review/scripts/split_diff.py --json --json-key diff --output-dir scratch/diff_chunks < input.json

How to Combine Subdivided Reviews

After performing subdivided reviews, use the Synthesis step to create the final output:

1. Deduplicate: Ensure that the same issue found in multiple passes or files is not reported multiple times unless it manifests differently.
2. Prioritize: Group comments by severity. Ensure critical and high-severity issues are highlighted at the top.
3. Cohesiveness: Ensure the tone and style of all comments are consistent, following the natural writing skill.