Code Review Playbook
This skill provides a comprehensive framework for effective code reviews that improve code quality, share knowledge, and foster collaboration. Whether you're a reviewer giving feedback or an author preparing code for review, this playbook ensures reviews are thorough, consistent, and constructive.
Overview
- Reviewing pull requests or merge requests
- Preparing code for review (self-review)
- Establishing code review standards for teams
- Training new developers on review best practices
- Resolving disagreements about code quality
- Improving review processes and efficiency
Upstream coverage (do not restate)
This skill is a thin wrapper. General review craft is documented first-party elsewhere;
only OrchestKit's own decisions live here. Load Read("references/ork-delta.md")
for the house rules that survived the retired files.
| Topic |
Go here instead |
| Review philosophy, speed, tone, PR sizing |
https://google.github.io/eng-practices/review/ |
| Conventional comment labels and decorations |
references/conventional-comments.md, https://conventionalcomments.org/ |
| OWASP Top 10 review checks |
rules/security-baseline.md, https://owasp.org/Top10/ |
| Generic language and framework review checklists |
rules/typescript-quality.md, rules/python-quality.md, rules/linting-biome-rules.md |
| Review report shape and multi-agent full-PR review |
ork:review-pr |
| Applying findings to the working tree |
/code-review --fix, /simplify (see below) |
| Security-only pass over the current branch |
/security-review |
| GitHub review mechanics (approve, request changes, inline comments) |
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests |
Conventional Comments
issue [blocking]: Missing error handling for API call
If the API returns a 500 error, this will crash. Add try/catch.
security [blocking]: API endpoint is not authenticated
The /api/admin/users endpoint is missing auth middleware.
Load Read("references/conventional-comments.md") for the full format, labels (praise, nitpick, suggestion, issue, question, security, bug, breaking), decorations ([blocking], [non-blocking], [if-minor]), and examples.
Review Process
1. Before Reviewing
Check Context:
- Read the PR/MR description
- Understand the purpose and scope
- Review linked tickets or issues
- Check CI/CD pipeline status
Verify Automated Checks:
Set Aside Time:
- Small PR (< 200 lines): 15-30 minutes
- Medium PR (200-500 lines): 30-60 minutes
- Large PR (> 500 lines): 1-2 hours (or ask to split)
2. During Review
Follow a Pattern:
High-Level Review (5-10 minutes)
- Read PR description and understand intent
- Skim all changed files to get overview
- Verify approach makes sense architecturally
- Check that changes align with stated purpose
Detailed Review (20-45 minutes)
- Line-by-line code review
- Check logic, edge cases, error handling
- Verify tests cover new code
- Look for security vulnerabilities
- Ensure code follows team conventions
Testing Considerations (5-10 minutes)
- Are tests comprehensive?
- Do tests test the right things?
- Are edge cases covered?
- Is test data realistic?
Documentation Check (5 minutes)
- Are complex sections commented?
- Is public API documented?
- Are breaking changes noted?
- Is README updated if needed?
3. After Reviewing
Provide Clear Decision:
- ✅ Approve: Code is ready to merge
- 💬 Comment: Feedback provided, no action required
- 🔄 Request Changes: Issues must be addressed before merge
Respond to Author:
- Answer questions promptly
- Re-review after changes made
- Approve when issues resolved
- Thank author for addressing feedback
Review Checklists
General Code Quality
Security
Quick Start Guide
For Reviewers:
- Read PR description and understand intent
- Check that automated checks pass
- Do high-level review (architecture, approach)
- Do detailed review (logic, edge cases, tests)
- Use conventional comments for clear communication
- Provide decision: Approve, Comment, or Request Changes
For Authors:
- Write clear PR description
- Perform self-review before requesting review
- Ensure all automated checks pass
- Keep PR focused and reasonably sized (< 400 lines)
- Respond to feedback promptly and respectfully
- Make requested changes or explain reasoning
CC Built-in Review Commands (2.1.152+)
This playbook is the manual framework; Claude Code ships built-in commands that automate parts of it:
/code-review — reviews the current diff for correctness bugs and reuse/simplification/efficiency cleanups.
/code-review --fix (CC 2.1.152+) — runs the review then applies the findings to your working tree (a bug-hunting review covering correctness plus reuse/simplification/efficiency).
/code-review --comment — posts findings as inline PR comments.
/simplify — CC 2.1.154 changed this: it now runs a cleanup-only review (reuse, simplification, efficiency, altitude) and applies the fixes — it no longer invokes the full /code-review --fix bug-hunt. Reach for /simplify for tidy-ups, /code-review --fix for bug-finding-plus-fix.
Use the built-ins for fast diff-scoped passes; use ork:review-pr for the multi-agent, full-PR review (security + testing + architecture).
Skill Version: 2.0.0
Last Updated: 2026-01-08
Maintained by: OrchestKit
Related Skills
ork:architecture-patterns - Enforce testing and architectural best practices during code review
ork:security-patterns - Auth, input validation, and OWASP patterns to complement manual review
ork:testing-unit - Unit testing patterns to verify during review
Rules
Each category has individual rule files in rules/ loaded on-demand:
| Category |
Rule |
Impact |
Key Pattern |
| TypeScript Quality |
rules/typescript-quality.md |
HIGH |
No any, Zod validation, exhaustive switches, React 19 |
| Python Quality |
rules/python-quality.md |
HIGH |
Pydantic v2, ruff, mypy strict, async timeouts |
| Security Baseline |
rules/security-baseline.md |
CRITICAL |
No secrets, auth on endpoints, input validation |
| Linting |
rules/linting-biome-setup.md |
HIGH |
Biome setup, ESLint migration, gradual adoption |
| Linting |
rules/linting-biome-rules.md |
HIGH |
Biome config, type-aware rules, CI integration |
Total: 5 rules across 4 categories
Available Scripts
There is deliberately no review-report template here; ork:review-pr owns that output
shape. See references/ork-delta.md.
1---2name: code-review-playbook3license: MIT4compatibility: "Claude Code 2.1.277+."5description: "Review process, conventional comments, language checklists and feedback templates. Use when reviewing code or standardizing review practice. To review a PR end to end, use review-pr."6context: inherit7user-invocable: false8hooks:9 PostToolUse:10 - matcher: "Write|Edit"11 hooks:12 - type: command13 command: "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs skill/pattern-consistency-enforcer"14effort: low15model: haiku16metadata:17 source: https://skillmd.com/skills/yonatangross/code-review-playbook18 category: document-asset-creation19 version: "2.0.0"20 author: "OrchestKit"21 complexity: "low"22 tags: "code-review, quality, collaboration, best-practices, testing"23allowed-tools: "Read Glob Grep WebFetch WebSearch"24---2526# Code Review Playbook27This skill provides a comprehensive framework for effective code reviews that improve code quality, share knowledge, and foster collaboration. Whether you're a reviewer giving feedback or an author preparing code for review, this playbook ensures reviews are thorough, consistent, and constructive.2829## Overview30- Reviewing pull requests or merge requests31- Preparing code for review (self-review)32- Establishing code review standards for teams33- Training new developers on review best practices34- Resolving disagreements about code quality35- Improving review processes and efficiency3637## Upstream coverage (do not restate)3839This skill is a thin wrapper. General review craft is documented first-party elsewhere;40only OrchestKit's own decisions live here. Load `Read("references/ork-delta.md")`41for the house rules that survived the retired files.4243| Topic | Go here instead |44|-------|-----------------|45| Review philosophy, speed, tone, PR sizing | https://google.github.io/eng-practices/review/ |46| Conventional comment labels and decorations | `references/conventional-comments.md`, https://conventionalcomments.org/ |47| OWASP Top 10 review checks | `rules/security-baseline.md`, https://owasp.org/Top10/ |48| Generic language and framework review checklists | `rules/typescript-quality.md`, `rules/python-quality.md`, `rules/linting-biome-rules.md` |49| Review report shape and multi-agent full-PR review | `ork:review-pr` |50| Applying findings to the working tree | `/code-review --fix`, `/simplify` (see below) |51| Security-only pass over the current branch | `/security-review` |52| GitHub review mechanics (approve, request changes, inline comments) | https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests |5354---5556## Conventional Comments5758```59issue [blocking]: Missing error handling for API call60If the API returns a 500 error, this will crash. Add try/catch.6162security [blocking]: API endpoint is not authenticated63The /api/admin/users endpoint is missing auth middleware.64```6566Load `Read("references/conventional-comments.md")` for the full format, labels (praise, nitpick, suggestion, issue, question, security, bug, breaking), decorations ([blocking], [non-blocking], [if-minor]), and examples.6768---6970## Review Process7172### 1. Before Reviewing7374**Check Context:**75- Read the PR/MR description76- Understand the purpose and scope77- Review linked tickets or issues78- Check CI/CD pipeline status7980**Verify Automated Checks:**81- [ ] Tests are passing82- [ ] Linting has no errors83- [ ] Type checking passes84- [ ] Code coverage meets targets85- [ ] No merge conflicts8687**Set Aside Time:**88- Small PR (< 200 lines): 15-30 minutes89- Medium PR (200-500 lines): 30-60 minutes90- Large PR (> 500 lines): 1-2 hours (or ask to split)9192### 2. During Review9394**Follow a Pattern:**95961. **High-Level Review** (5-10 minutes)97 - Read PR description and understand intent98 - Skim all changed files to get overview99 - Verify approach makes sense architecturally100 - Check that changes align with stated purpose1011022. **Detailed Review** (20-45 minutes)103 - Line-by-line code review104 - Check logic, edge cases, error handling105 - Verify tests cover new code106 - Look for security vulnerabilities107 - Ensure code follows team conventions1081093. **Testing Considerations** (5-10 minutes)110 - Are tests comprehensive?111 - Do tests test the right things?112 - Are edge cases covered?113 - Is test data realistic?1141154. **Documentation Check** (5 minutes)116 - Are complex sections commented?117 - Is public API documented?118 - Are breaking changes noted?119 - Is README updated if needed?120121### 3. After Reviewing122123**Provide Clear Decision:**124- ✅ **Approve**: Code is ready to merge125- 💬 **Comment**: Feedback provided, no action required126- 🔄 **Request Changes**: Issues must be addressed before merge127128**Respond to Author:**129- Answer questions promptly130- Re-review after changes made131- Approve when issues resolved132- Thank author for addressing feedback133134---135136## Review Checklists137138### General Code Quality139140- [ ] **Readability**: Code is easy to understand141- [ ] **Naming**: Variables and functions have clear, descriptive names142- [ ] **Comments**: Complex logic is explained143- [ ] **Formatting**: Code follows team style guide144- [ ] **DRY**: No unnecessary duplication145- [ ] **SOLID Principles**: Code follows SOLID where applicable146- [ ] **Function Size**: Functions are focused and < 50 lines147- [ ] **Cyclomatic Complexity**: Functions have complexity < 10148149### Security150151- [ ] **Authentication**: Protected endpoints require auth152- [ ] **Authorization**: Users can only access their own data153- [ ] **Input Sanitization**: SQL injection, XSS prevented154- [ ] **Secrets Management**: No hardcoded credentials or API keys155- [ ] **Encryption**: Sensitive data encrypted at rest and in transit156- [ ] **Rate Limiting**: Endpoints protected from abuse157158---159160## Quick Start Guide161162**For Reviewers:**1631. Read PR description and understand intent1642. Check that automated checks pass1653. Do high-level review (architecture, approach)1664. Do detailed review (logic, edge cases, tests)1675. Use conventional comments for clear communication1686. Provide decision: Approve, Comment, or Request Changes169170**For Authors:**1711. Write clear PR description1722. Perform self-review before requesting review1733. Ensure all automated checks pass1744. Keep PR focused and reasonably sized (< 400 lines)1755. Respond to feedback promptly and respectfully1766. Make requested changes or explain reasoning177178---179180## CC Built-in Review Commands (2.1.152+)181182This playbook is the manual framework; Claude Code ships built-in commands that automate parts of it:183184- **`/code-review`** — reviews the current diff for correctness bugs and reuse/simplification/efficiency cleanups.185- **`/code-review --fix`** (CC 2.1.152+) — runs the review then applies the findings to your working tree (a bug-hunting review covering correctness plus reuse/simplification/efficiency).186- **`/code-review --comment`** — posts findings as inline PR comments.187- **`/simplify`** — **CC 2.1.154 changed this**: it now runs a **cleanup-only** review (reuse, simplification, efficiency, altitude) and applies the fixes — it no longer invokes the full `/code-review --fix` bug-hunt. Reach for `/simplify` for tidy-ups, `/code-review --fix` for bug-finding-plus-fix.188189Use the built-ins for fast diff-scoped passes; use `ork:review-pr` for the multi-agent, full-PR review (security + testing + architecture).190191---192193**Skill Version**: 2.0.0194**Last Updated**: 2026-01-08195**Maintained by**: OrchestKit196197## Related Skills198199- `ork:architecture-patterns` - Enforce testing and architectural best practices during code review200- `ork:security-patterns` - Auth, input validation, and OWASP patterns to complement manual review201- `ork:testing-unit` - Unit testing patterns to verify during review202203## Rules204205Each category has individual rule files in `rules/` loaded on-demand:206207| Category | Rule | Impact | Key Pattern |208|----------|------|--------|-------------|209| TypeScript Quality | `rules/typescript-quality.md` | HIGH | No `any`, Zod validation, exhaustive switches, React 19 |210| Python Quality | `rules/python-quality.md` | HIGH | Pydantic v2, ruff, mypy strict, async timeouts |211| Security Baseline | `rules/security-baseline.md` | CRITICAL | No secrets, auth on endpoints, input validation |212| Linting | `rules/linting-biome-setup.md` | HIGH | Biome setup, ESLint migration, gradual adoption |213| Linting | `rules/linting-biome-rules.md` | HIGH | Biome config, type-aware rules, CI integration |214215**Total: 5 rules across 4 categories**216217## Available Scripts218219- **`scripts/review-pr.md`** - Dynamic PR review with auto-fetched GitHub data220 - Auto-fetches: PR title, author, state, changed files, diff stats, comments count221 - Usage: `review-pr [PR-number]`222 - Requires: GitHub CLI (`gh`)223 - Uses `$ARGUMENTS` and `!command` for live PR data224225- **`assets/pr-template.md`** - PR description template226227There is deliberately no review-report template here; `ork:review-pr` owns that output228shape. See `references/ork-delta.md`.