code-review

name	code-review
description	Thorough, critical code review focused on correctness, business logic, implementation, tests, and documentation. Use when reviewing code changes, pull requests, or implementations. Only invoke when user explicitly asks for code review.

Code Review Instructions

Review the specified code thoroughly and critically. Prioritize finding real issues over being agreeable. Focus on functional correctness, business behavior, implementation, tests, and documentation.

Perform the entire review yourself. Do NOT delegate to subagents or use the Task tool for discovery, analysis, verification, or any other part of the review.

What to Review

If $ARGUMENTS specifies files or paths, review those. Or if user specifies a target branch, review that. Otherwise, review uncommitted changes in the current repository. If there are no uncommitted changes, review the changes on the branch compared to upstream (main or master).

Review Criteria (The 5 C's)

Correctness

• Business rules, domain invariants, calculations, and state transitions
• Logic errors, edge cases, off-by-one errors, race conditions, nil/null handling
• Ordering, retries, idempotency, transaction boundaries, and partial failures
• Concurrency: data races, deadlocks, improper synchronization
• Compatibility: backward compatibility, API stability, migration path (only when applicable)
• Tests actually verify the behavior they claim to test

Completeness

• All requirements addressed
• Error paths handled
• Edge cases covered in tests
• Documentation covers usage, parameters, return values, errors

Conciseness

• Code: No dead code, redundant logic, or unnecessary abstractions
• Design: Solution complexity is appropriate for the problem
• Tests are focused and meaningful without excessive setup
• Documentation is precise without filler

Consistency

• Code: Follows established patterns, naming conventions, style
• Design: Principles upheld, architecture coherent (backpressure propagation, error handling philosophy, resource ownership, concurrency model, abstraction boundaries)
• Test style matches project conventions
• Documentation format matches existing docs

Clarity

• Code is readable and self-documenting
• Complex logic is explained where necessary
• Tests clearly express intent
• Documentation is unambiguous

Output Format

Structure your review with clearly visible priority sections. Each issue gets a unique ID based on priority.

# Code Review Findings

## Critical - MUST FIX
<!-- Broken business invariants, data loss or corruption risk, unusable core flows, broken builds -->

### C1: [Short descriptive title]
**File**: `path/to/file.go:123`
**Issue**: Clear description of the problem and its impact.
**Possible solutions**: 1-3 concrete fixes, ordered by preference.
**Example**: Optional. Include only for complex issues that span multiple files or several locations in one file.

---

### C2: [Another critical issue]
...

## High - Should Fix
<!-- Correctness issues, missing error handling, significant edge cases, incomplete tests -->

### H1: [Title]
**File**: `path/to/file.go:456`
**Issue**: Description of the problem.
**Possible solutions**: 1-3 concrete fixes, ordered by preference.
**Example**: Optional. Include only for complex issues that span multiple files or several locations in one file.

---

## Medium - Consider Fixing
<!-- Code clarity issues, minor edge cases, minor optimizations -->

### M1: [Title]
**File**: `path/to/file.go:789`
**Issue**: What's suboptimal or unclear.
**Recommended solution**: The single most appropriate concrete fix.
**Example**: Optional. Include only for complex issues that span multiple files or several locations in one file.

---

## Low - Nice to Have
<!-- Style, consistency, documentation improvements -->

### L1: [Title]
**File**: `path/to/file.go:101`
**Issue**: Minor concern.
**Recommended solution**: The single most appropriate concrete fix.
**Example**: Optional. Include only for complex issues that span multiple files or several locations in one file.

---

## Questions
<!-- Clarifications needed -->

### Q1: [Question]
Context and what needs clarification.

Issue ID Convention:

• Critical: C1, C2, C3...
• High: H1, H2, H3...
• Medium: M1, M2, M3...
• Low: L1, L2, L3...
• Questions: Q1, Q2, Q3...

For Critical and High issues, include Possible solutions with 1-3 concrete fixes ordered by preference. For Medium and Low issues, include only the single most appropriate fix under Recommended solution; do not list alternatives. Include Example only for complex issues, especially issues that span multiple files or several locations in one file. Omit empty sections.

Visibility Guidelines:

• Start with Critical issues - make them impossible to miss
• Use horizontal rules (---) between issues for clear separation
• Bold the priority level in section headers