Review
Run all review dimensions against the current branch and produce one unified review. Approve when a change improves overall code health, even if it isn't perfect.
Scope
Review only what changed on the current branch against main, but read enough surrounding code and docs to understand conventions and boundaries.
Do not duplicate the same issue across categories.
Change sizing
Before reviewing, check the diff size:
- ~100 lines: good, reviewable in one pass.
- ~300 lines: acceptable if one logical change.
- ~1000 lines: too large — ask the author to split before reviewing.
Refactoring mixed with feature work is two changes. Flag it.
Workflow
- Determine diff scope:
git log main..HEAD --onelineandgit diff main...HEAD --stat. - If no commits ahead of
main, report that and stop. - Read changed files in full, plus any project-level convention docs.
- Review tests first — they reveal intent and coverage gaps.
- Run each review dimension: Style, Architecture, Docs, Security, Tests. Load the corresponding skill for each dimension when possible.
- Merge findings: deduplicate, keep strongest framing per root issue.
- Label every finding by severity:
| Label | Meaning | Action |
|---|---|---|
| *(unmarked)* | Must fix | Address before merge |
| Critical: | Blocks merge | Security, data loss, broken functionality |
| Nit: | Optional | Style preference, minor improvement |
| Consider: | Suggestion | Worth thinking about, not required |
- Order by merge relevance: must-fix → should-fix → optional.
Dependency review
If the change adds a dependency, check:
- Does the existing stack already solve this?
- Is it actively maintained?
- What's the size impact?
- Any known vulnerabilities?
Every dependency is a liability.
Fix policy
Default to fixing all findings — including trivial ones. Small issues left unfixed accumulate into tech debt. If a finding is worth reporting, it's worth fixing before merge.
Output
One section per review dimension (Style, Architecture, Documentation, Security, Tests), then a summary table: category | must-fix | should-fix | optional. Note categories with no findings.
See also
style,architecture,docs,security,testsfor dimension-specific depthreferences/security-checklist.mdfor concrete abuse-path checksreferences/testing-patterns.mdfor test-quality review heuristics
Red flags
- Reviewing only the diff without reading touched files in context
- Duplicating the same root issue across categories
- Generic cleanup wishlists
- Speculative issues without evidence
- Broad rewrite suggestions out of scope
- "LGTM" without evidence of review
- Softening real issues — if it's a bug, say so directly
- Accepting "I'll fix it later" — require cleanup before merge