.agents/agents/reidbaker-agent/skills/code-review/references/splitting_reviews.md - mirrors/flutter - Git at Google

 # 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:**
 ```bash
 python3 agents/skills/code-review/scripts/split_diff.py --output-dir scratch/diff_chunks < diff.txt
 ```

 For JSON inputs:
 ```bash
 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](../../natural-writing/SKILL.md) skill.
	# 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:
	```bash
	python3 agents/skills/code-review/scripts/split_diff.py --output-dir scratch/diff_chunks < diff.txt
	```

	For JSON inputs:
	```bash
	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](../../natural-writing/SKILL.md) skill.