Review overall codebase health, architecture, and patterns using Google's engineering principles. Takes optional focus area. Use when the user wants to review code quality, assess architecture, or says "/review-codebase" or "/review-codebase 'API layer'".
Review overall codebase health, architecture, and patterns following Google's engineering practices.
This skill performs a comprehensive codebase review examining overall code health, architecture, patterns, and adherence to engineering principles across the entire codebase (or a specified subset).
Key difference from PR review: There's no diff to examine. Instead of reviewing changes, we review overall structure and health of the codebase.
Use this skill when you want to:
Follow this multi-phase process to produce thorough codebase reviews:
Conduct a complete codebase review following these steps:
Check we have a GitHub remote:
git remote -v
STOP if:
If a focus area was provided as an argument (e.g., "API layer", "tests", "auth system"):
/review-codebase "API layer"If no argument was provided:
/review-codebaseUse the Task tool with subagent_type: "Explore" for thorough codebase exploration:
Tool: Task
Parameters:
subagent_type: "Explore"
description: "Explore codebase structure"
prompt: |
Explore this codebase to understand its structure, architecture, and key patterns.
[If focus area provided:]
Focus area: <focus-area>
Concentrate your exploration on this area of the codebase.
[Always:]
Identify:
- Overall project structure and organisation
- Key architectural patterns and decisions
- Main components and their relationships
- Testing approach and organisation
- Documentation quality (README, API docs, etc.)
- Style and naming conventions
- Areas of high complexity
Use thoroughness level: "very thorough"
Return:
1. Project structure overview
2. Key files and directories
3. Architectural patterns observed
4. Notable patterns (good and bad)
5. Areas that warrant closer review
The Explore agent will:
Using the exploration results, conduct a systematic review across these categories:
1. Architecture & Design
2. Code Health
3. Testing Strategy
4. Naming & Conventions
5. Documentation
6. Complexity Patterns
7. Style Consistency
8. Error Handling & Robustness
Organise findings by category with severity levels:
Severity Levels:
Include:
After completing the initial review, launch a subagent using the Task tool to critique the review. Using a separate agent provides a genuinely fresh perspective.
You MUST use the Task tool with subagent_type: "general-purpose" to run the critique. Do not attempt to critique your own review directly.
Provide the subagent with:
The critique subagent examines the initial review and looks for:
Example Task tool invocation:
Tool: Task
Parameters:
subagent_type: "general-purpose"
description: "Critique codebase review"
prompt: |
Critique this codebase review. You have access to all tools including Read, Glob, and Grep.
Review scope: [Full codebase / Focus area: "X"]
Key files/areas examined in initial review:
- [list files or areas]
Initial review output:
## Summary
[paste your complete review summary here]
## Findings
[include all findings from your initial review]
## Positive Observations
[include positive observations]
Your job is to find what the review missed or got wrong:
1. Use Glob/Grep to explore the codebase yourself
2. Read key files to verify findings and check for missed patterns
3. Look for systemic patterns the initial review may have missed
4. Verify the severity assessments are appropriate
5. Check if any findings are false positives
6. Identify overlooked areas that should have been examined
Return your critique as:
- New patterns/issues found (with severity and examples)
- Severity adjustments needed (with justification)
- False positives to remove (with reasoning)
- Overlooked areas to examine
The subagent has full access to codebase exploration tools. It should independently verify findings and look for missed patterns.
Combine the initial review with critique findings into a final output:
[Critique][Upgraded from Suggestion])After synthesis, decide whether another critique pass would add value:
Limit to a maximum of 2 critique passes. Beyond this, additional passes rarely surface new insights and the cost outweighs the benefit.
Format the review clearly using the structure below.
## Summary
[2-3 sentence overview of codebase health and key findings]
## Findings
### Architecture & Design
- [Severity] Pattern: Description
- Examples: file1:line, file2:line
- [Critique] [Severity] Pattern: Description (new pattern found by critique)
- Examples: file1:line, file2:line
- [Upgraded from Suggestion] [Critical] Pattern: Description (severity changed by critique)
- Examples: file1:line, file2:line
### Code Health
- [Severity] Pattern: Description
- Examples: file1:line, file2:line
### Testing Strategy
- [Severity] Pattern: Description
- Examples: file1:line, file2:line
### Naming & Conventions
- [Severity] Pattern: Description
- Examples: file1:line, file2:line
### Documentation
- [Severity] Pattern: Description
- Examples: file1:line, file2:line
### Complexity Patterns
- [Severity] Pattern: Description
- Examples: file1:line, file2:line
### Style Consistency
- [Severity] Pattern: Description
- Examples: file1:line, file2:line
### Error Handling & Robustness
- [Severity] Pattern: Description
- Examples: file1:line, file2:line
## Positive Observations
- Good pattern: Description
- Examples: file1:line, file2:line
- [Critique] Good pattern: Description (new positive pattern found by critique)
- Examples: file1:line, file2:line
## Overall Assessment
[High-level assessment of codebase health]
[Key areas for improvement]
[Strengths worth preserving]
[Critical] Pattern: Description[Critique], e.g., [Critique] [Suggestion] Pattern: Description[Upgraded from Suggestion] [Critical] Pattern: DescriptionOmit empty categories. Focus on patterns and overall health, not individual line-by-line issues.
DO:
DON'T:
Full codebase review:
/review-codebase
Focused review:
/review-codebase "API layer"
/review-codebase "tests"
/review-codebase "authentication system"
Based on Google's Engineering Practices: Code Review Guidelines, adapted for codebase-level review rather than change-focused review.