/code-review-playbook

name: code-review-playbook
license: MIT
compatibility: "Claude Code 2.1.251+."
description: Structured review processes, conventional comments, language-specific checklists, and feedback templates. Use when reviewing PRs, conducting code review, or standardizing review practice.
version: 2.0.0
author: OrchestKit
tags: [code-review, quality, collaboration, best-practices]
context: inherit
agent: code-quality-reviewer
user-invocable: false
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      command: "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs skill/pattern-consistency-enforcer"
complexity: low
persuasion-type: discipline
effort: low
model: haiku
metadata:
  category: document-asset-creation
allowed-tools:
  - Read
  - Glob
  - Grep
  - WebFetch
  - WebSearch

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:**

• [ ] Tests are passing
• [ ] Linting has no errors
• [ ] Type checking passes
• [ ] Code coverage meets targets
• [ ] No merge conflicts

**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:**

1. **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

2. **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

3. **Testing Considerations** (5-10 minutes)

• Are tests comprehensive?
• Do tests test the right things?
• Are edge cases covered?
• Is test data realistic?

4. **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

• [ ] **Readability**: Code is easy to understand
• [ ] **Naming**: Variables and functions have clear, descriptive names
• [ ] **Comments**: Complex logic is explained
• [ ] **Formatting**: Code follows team style guide
• [ ] **DRY**: No unnecessary duplication
• [ ] **SOLID Principles**: Code follows SOLID where applicable
• [ ] **Function Size**: Functions are focused and < 50 lines
• [ ] **Cyclomatic Complexity**: Functions have complexity < 10

Security

• [ ] **Authentication**: Protected endpoints require auth
• [ ] **Authorization**: Users can only access their own data
• [ ] **Input Sanitization**: SQL injection, XSS prevented
• [ ] **Secrets Management**: No hardcoded credentials or API keys
• [ ] **Encryption**: Sensitive data encrypted at rest and in transit
• [ ] **Rate Limiting**: Endpoints protected from abuse

---

Quick Start Guide

**For Reviewers:** 1. Read PR description and understand intent 2. Check that automated checks pass 3. Do high-level review (architecture, approach) 4. Do detailed review (logic, edge cases, tests) 5. Use conventional comments for clear communication 6. Provide decision