reviewing-code by CaptainCrouton89

---
name: Reviewing Code
description: Systematically evaluate code changes for security, correctness, performance, and spec alignment. Use when reviewing PRs, assessing code quality, or verifying implementation against requirements.
---

# Reviewing Code

Evaluate code changes across security, correctness, spec alignment, performance, and maintainability. Apply sequential or parallel review based on scope.

## Quick Start

**Sequential (small PRs, <5 files):**
1. Gather context from feature specs and acceptance criteria
2. Review sequentially through focus areas
3. Report findings by priority
4. Recommend approval/revision/rework

**Parallel (large PRs, >5 files):**
1. Identify independent review aspects (security, API, UI, data)
2. Spawn specialist agents for each dimension
3. Consolidate findings
4. Report aggregate assessment

## Context Gathering

**Read documentation:**
- `docs/feature-spec/F-##-*.md` — Technical design and requirements
- `docs/user-stories/US-###-*.md` — Acceptance criteria
- `docs/api-contracts.yaml` — Expected API signatures
- `docs/data-plan.md` — Event tracking requirements (if applicable)
- `docs/design-spec.md` — UI/UX requirements (if applicable)
- `docs/system-design.md` — Architecture patterns (if available)
- `docs/plans/<slug>/plan.md` — Original implementation plan (if available)

**Determine scope:**
- Files changed and features affected (F-## IDs)
- Stories implemented (US-### IDs)
- API, database, or schema changes

## Quality Dimensions

**Security (/25)**
- Input validation and sanitization
- Authentication/authorization checks
- Sensitive data handling
- Injection vulnerabilities (SQL, XSS, etc.)

**Correctness (/25)**
- Logic matches acceptance criteria
- Edge cases handled properly
- Error handling complete
- Null/undefined checks present

**Spec Alignment (/20)**
- APIs match `docs/api-contracts.yaml`
- Data events match `docs/data-plan.md`
- UI matches `docs/design-spec.md`
- Implementation follows feature spec

**Performance (/15)**
- Algorithm efficiency
- Database query optimization
- Resource usage (memory, network)

**Maintainability (/15)**
- Code clarity and readability
- Consistent with codebase patterns
- Appropriate abstraction levels
- Comments where needed

**Total: /100**

## Finding Priority

### 🔴 CRITICAL (Must fix before merge)
- Security vulnerabilities
- Broken functionality
- Spec violations (API contract breaks)
- Data corruption risks

**Format:**
```
Location: file.ts:123
Problem: [Description]
Impact: [Risk/consequence]
Fix: [Specific change needed]
Spec reference: [docs/api-contracts.yaml line X]
```

### 🟡 IMPORTANT (Should fix)
- Logic bugs in edge cases
- Missing error handling
- Performance issues
- Missing analytics events
- Accessibility violations

### 🟢 NICE-TO-HAVE (Optional)
- Code style improvements
- Better abstractions
- Enhanced documentation

### ✅ GOOD PRACTICES
Highlight what was done well for learning

## Review Strategies

### Single-Agent Review
Best for <5 files, single concern:
1. Review sequentially through focus areas
2. Concentrate on 1-2 most impacted areas
3. Generate unified report

### Parallel Multi-Agent Review
Best for >5 files, multiple concerns:
1. Spawn specialized agents:
   - **Security:** `senior-engineer` for vulnerability assessment
   - **Architecture:** `Explore` for pattern compliance
   - **API Contracts:** `programmer` for endpoint validation
   - **Frontend:** `programmer` for UI/UX and accessibility
   - **Documentation:** `documentor` for comment quality and docs

2. Each agent reviews specific quality dimension
3. Consolidate findings into single report

## Report Structure

```
# Code Review: [Feature/PR]

## Summary
**Quality Score:** [X/100]
**Issues:** Critical: [N], Important: [N], Nice-to-have: [N]
**Assessment:** [APPROVE / NEEDS REVISION / MAJOR REWORK]

## Spec Compliance
- [ ] APIs match `docs/api-contracts.yaml`
- [ ] Events match `docs/data-plan.md`
- [ ] UI matches `docs/design-spec.md`
- [ ] Logic satisfies story AC

## Findings

### Critical Issues
[Issues with fix recommendations]

### Important Issues
[Issues that should be addressed]

### Nice-to-Have Suggestions
[Optional improvements]

### Good Practices
[What worked well]

## Recommendations
[Next steps: approval, revision needed, etc.]
```

## Fix Implementation

**Offer options:**
1. Fix critical + important issues
2. Fix only critical (minimum for safety)
3. Provide detailed explanation for learning
4. Review only (no changes)

**Parallel fixes for large revisions:**
- Spawn agents for independent fix areas
- Coordinate on shared dependencies
- Document each fix with location, change, and verification method

**Document format:**
```
✅ FIXED: [Issue name]
File: [path:line]
Change: [what changed]
Verification: [how to test]
```

## Documentation Updates

**Check if specs need updates:**
- Feature spec "Decisions" or "Deviations" if implementation differs
- Design spec if UI changed
- API contracts if endpoints modified (requires approval)
- Data plan if events changed

**Always flag for user approval before modifying specs.**

## Key Points

- Read all context documents before starting
- Focus on most impacted areas first
- Be thorough with security-sensitive code, API changes, and critical user flows
- Use scoring framework for comprehensive reviews
- Parallel review scales to large PRs
- Flag spec deviations for user decision