code-review git:20260303.09b1726A

Immutable. This exact content never changes and is served at /api/v1/blob/e33f1518f41f56c8.

---
name: code-review
description: >
  Review code for quality, bugs, and design issues. Use when the user says "review this code",
  "do a code review", "check this PR", "review this diff", "is this code good",
  "what's wrong with this code", "code quality check", or pastes code and wants feedback
  - even if they don't explicitly say "code review".
---

## Overview

Based on **"Clean Code"** by Robert C. Martin. Martin's central argument: code is read far more than it is written. Clean code reads like well-written prose - the reader can understand the intent without decoding it. A code review is not just a bug hunt - it's a check that the code communicates its intent clearly to the next developer who reads it.

## Workflow

### Step 1: Read for intent first
Before looking for bugs, read the code as a whole. Can you understand what it does without reading comments or documentation? If not, that's the first finding.

### Step 2: Check naming
Martin's rule: names should reveal intent. Review every variable, function, and class name.
- Does the name tell you what it does, not how it does it?
- Would a new team member understand this name without context?
- Are booleans named as predicates? (`isValid`, `hasPermission`, not `flag`, `check`)

Bad: `d = datetime.now() - start`
Good: `elapsed_time = datetime.now() - start`

### Step 3: Check function size and responsibility
Martin's single responsibility principle: a function should do one thing and do it well.
- Functions longer than 20 lines are candidates for extraction
- If a function needs a comment to explain what each section does, split it
- If a function has multiple levels of abstraction mixed together, extract

### Step 4: Check error handling
- Are errors handled explicitly or silently swallowed?
- Do error messages help the caller understand what went wrong and how to fix it?
- Are exceptions used for exceptional cases only - not flow control?

### Step 5: Check for duplication
Martin's DRY principle: duplication is the root of all evil in software.
- Is this logic duplicated elsewhere in the codebase?
- Could this be extracted to a shared utility?
- Are magic numbers duplicated? (extract to named constants)

### Step 6: Check tests
- Are there tests for the new or changed behavior?
- Do tests cover the happy path AND failure cases?
- Are test names descriptive? (`test_login_fails_with_invalid_password` not `test_login_2`)

### Step 7: Write the review
Structure feedback as:
- **Must fix** - bugs, security issues, broken contracts
- **Should fix** - Clean Code violations that will cause maintenance pain
- **Consider** - style suggestions, optional improvements
- **Praise** - what was done well (important for team morale and learning)

## Anti-Patterns

**1. Nitpicking style without flagging real issues**
Bad: 10 comments about variable naming, zero comments about a missing null check.
Good: Prioritize by impact. Fix correctness first, then clarity, then style.

**2. No positive feedback**
Bad: Only listing problems.
Good: Note what was done well. Reviewers who only criticize produce defensive engineers.

**3. Vague feedback**
Bad: "This function is too complex."
Good: "This function does 3 things: validates input, transforms data, and saves to DB. Extract each into its own function so each can be read and tested independently."

**4. Reviewing without running the code**
Bad: Approving a PR without checking it builds and tests pass.
Good: CI should enforce this automatically. If CI is absent, run tests locally before approving.

## Quality Checklist

- [ ] Intent is clear - code reads without needing to decode it
- [ ] Names reveal intent at every level (variables, functions, classes)
- [ ] Functions have single responsibility and fit in one screen
- [ ] Error handling is explicit - no silent failures
- [ ] No unnecessary duplication - DRY applied
- [ ] Tests cover happy path and failure cases
- [ ] Must fix / should fix / consider clearly separated
- [ ] At least one specific piece of positive feedback included