---
name: code-review
description: Review code for Clean Architecture compliance. Checks API, Service,
  and Repository layers against project rules in .claude/rules/. Supports
  --staged and --branch scope options; add --fix to auto-correct violations.
argument-hint: "[path] [--staged|--branch] [--fix]"
allowed-tools: Read Glob Grep Edit Bash(git *) Bash(find *)
---

# Code Review — Clean Architecture Compliance

Review code changes for Clean Architecture violations.

**Arguments**: $ARGUMENTS

| Option | Review scope |
| --- | --- |
| (none) | Files changed in the last 5 commits |
| `path` | The given file or directory only |
| `--staged` | Files staged for commit |
| `--branch` | Current branch vs main |
| `--fix` | Combine with any scope: auto-fix violations after reporting |

## Context

- Project rules: !`find .claude/rules -name "*.md" 2>/dev/null | sort`
- Staged files: !`git diff --name-only --cached 2>/dev/null`
- Current branch: !`git branch --show-current`

## What to Check

Read every rule file listed under "Project rules" above before reviewing.
The checklists below are the baseline; project rules take precedence.

### Architecture Layers

**API Layer** (`src/**/api/**/*.py`):
- ✅ Services injected via `Depends()`, not manually instantiated
- ✅ No Repository imports or direct calls
- ✅ No business logic (calculations, validations, transformations)
- ✅ Proper HTTP exception handling
- ✅ Return type wrapped in SuccessResponse

**Service Layer** (`src/**/services/**/*.py`):
- ✅ Public methods return Pydantic BaseModel, **NEVER Dict**
- ✅ Private methods (`_` prefix) may return ORM for internal use
- ✅ Only calls Repository, not other layers directly
- ✅ Business logic properly encapsulated
- ✅ Other services injected via DI, not manual instantiation

**Repository Layer** (`src/**/repositories/**/*.py`):
- ✅ Only CRUD operations, no business logic
- ✅ Returns SQLAlchemy models only
- ✅ No Service layer imports
- ✅ No calls to other repositories

### Data Structures

**Models** (`src/**/models/**/*.py`):
- ✅ SQLAlchemy 2.0+: Mapped types, mapped_column
- ✅ No business logic
- ✅ TYPE_CHECKING for circular imports

**Schemas** (`src/**/schemas/**/*.py`):
- ✅ Pydantic v2: ConfigDict, field_validator, model_validate
- ✅ Response schemas have `from_attributes=True`
- ✅ No business logic

### Infrastructure

**Tasks** (`src/**/tasks/**/*.py`):
- ✅ DI pattern for service acquisition
- ✅ Independent DB session (not request context)

## Review Process

1. Parse arguments: determine scope (path / git option) and whether `--fix` is set
2. Read the architecture rules listed in Context
3. Analyze each target file against the checklists
4. Report violations with `file:line` references and severity
5. If `--fix`: apply corrections, then re-verify the fixed files

## Severity Levels

- **CRITICAL**: Violates core architecture (Dict return, wrong imports, ORM to API)
- **WARNING**: Not ideal but acceptable
- **SUGGESTION**: Improvement recommendations

## Output Format

End with a summary line:

```
Summary: N critical, N warnings, N suggestions
```