Code Review

Skill for validating implemented code against project standards.

Use for: Validate code, identify violations, auto-fix (autopilot) Do not use for:

• Implementing new features (use add-backend-development / add-frontend-development)
• Planning or specifying work (use add-planning / add-feature-specification)
• Codebase discovery or architecture analysis (use add-feature-discovery / add-architecture-discovery)

Reference: Always consult CLAUDE.md for general project standards.

---

MANDATORY RULE: TodoWrite

BEFORE starting any review, you MUST create a todo list using TodoWrite.

The code-review agent MUST create todos for each validation category and for each changed file. This ensures:

1. Progress visibility for the user
2. No validation is forgotten
3. Traceability of fixes

---

Reference Skills

Load BEFORE reviewing:

• Backend: {{skill:add-backend-development/SKILL.md}}
• Database: {{skill:add-database-development/SKILL.md}}
• Frontend (Code): {{skill:add-frontend-development/SKILL.md}}
• Frontend (UI): {{skill:add-ux-design/SKILL.md}}
• Security: {{skill:add-security-audit/SKILL.md}}

---

Validation Categories

1. Spec Compliance (CRITICAL)

Spec vs implementation gap = the root cause of features that "pass review" but diverge from what was planned.

Sources (lookup):

{"sources":{"contracts":"docs/features/${FEATURE_ID}/plan.md (prose: routes, services, DTOs, queues)","tick_state":"docs/features/${FEATURE_ID}/tasks.md → ## Acceptance Checklist"}}

Validation procedure:

1. READ contracts from plan.md prose (routes, services, DTOs, queues)
2. READ tick state from tasks.md → ## Acceptance Checklist (each item ends with (RFNN/RNNN) reference)
3. For EACH contract item:
   1. Locate implementation with file:line
   2. Validate EXISTENCE and BEHAVIOR:
      • Route exists AND accepts correct params?
      • Service is generic as spec OR hardcoded?
      • DTO has all specified fields?
   3. Cross-reference: do items cover ALL RF/RN from about.md?
   4. Status: COMPLIANT | DIVERGENT (exists but differs) | MISSING

Examples:

Type	Spec	Code	Fix
DIVERGENT	POST /billing/webhook/:provider	POST /webhook (fixed route)	Refactor route to accept :provider param
DIVERGENT	WebhookNormalizerService (generic)	StripeWebhookService (hardcoded)	Extract generic interface, rename service
MISSING	WebhookSignatureGuard	No guard found	Implement guard or document explicit scope exclusion

Spec Compliance scoring:

• COMPLIANT (all items match): full points
• DIVERGENT (functional but differs): -1 per item
• MISSING (not implemented): -2 per item, blocks merge if RF-linked

---

2. Architecture Contract (MOST CRITICAL)

Architecture violation = CRITICAL BLOCKER. Fix BEFORE any other validation.

Source: CLAUDE.md → ## Architecture Contract.

Validation steps:

For EACH new/modified file:

1. Identify the file's layer/package
2. Grep imports of @org/* (or project alias)
3. Verify against Import rules from the contract
4. Verify the artefact is in the correct package (Placement)

Examples:

Violation	Fix
interfaces imports database	Move artefact or adjust import
Service-contract DTO in database	Move DTO to interfaces
domain imports anything	Remove import — domain has zero deps

---

3. IoC Configuration (CRITICAL)

Code without correct IoC does NOT work at runtime.

Checklist by component type (lookup)

{"iocChecklist":{"Service":{"decorator":"@Injectable()","providers":"feature module","exports":false,"controllers":false,"indexTs":false},"Repository":{"decorator":"@Injectable()","providers":"db module","exports":"db module","controllers":false,"indexTs":"libs/"},"Handler":{"decorator":"@Injectable()","providers":"feature module","exports":false,"controllers":false,"indexTs":"NEVER"},"Guard":{"decorator":"@Injectable()","providers":"feature/global","exports":false,"controllers":false,"indexTs":false},"Controller":{"decorator":"@Controller()","providers":false,"exports":false,"controllers":"feature module","indexTs":false}}}

Files to verify for IoC

File	Check
apps/backend/src/app.module.ts	imports[] contains module
[feature].module.ts	providers[], controllers[], imports[]
libs/app-database/src/app-database.module.ts	providers[], exports[] for repos
libs/app-database/src/index.ts	public repo exports
libs/app-database/src/types/Database.ts	new table types
libs/domain/src/index.ts	new entity/enum exports

Common IoC Errors

Error	Cause	Fix
Nest can't resolve dependencies of X	X not in providers[] or X's dependency not registered	Add X and its dependencies to providers[]
X is not a provider	Missing @Injectable() or not registered	Add decorator and register in providers[]
Module X not found	Module not imported in AppModule	Add to AppModule.imports[]
Repository not found	Repo not exported in db module exports[]	Add to AppDatabaseModule exports[]
404 on endpoint	Controller not registered or module not imported	Check controllers[] and AppModule.imports[]

---

4. RESTful Compliance (CRITICAL)

Rule	Correct	Wrong
HTTP method	GET read, POST create, DELETE remove	POST for read
URL	/users (noun)	/getUsers (verb)
Status	201 POST, 204 DELETE	200 for all

---

5. Contract Validation (CRITICAL)

Frontend ↔ Backend:

Backend	Frontend
Date	string
Enum	union type

Sync required / optional fields between backend and frontend.

JSONB rules:

• NO double parse
• NO double stringify
• Kysely handles automatically

---

6. Security (OWASP)

Category	Check
Injection	parametrized queries
Auth	guards applied
Data Exposure	no secrets in logs
Access Control	filter by account_id
XSS	outputs sanitized

Multi-tenant:

• EVERY query filters account_id
• account_id from JWT, not body

---

7. SOLID Principles

• SRP: one class, one responsibility
• OCP: open for extension, closed for modification
• LSP: subtypes substitutable
• ISP: specific interfaces over general
• DIP: depend on abstractions

---

8. Code Quality

• No any type
• DTOs follow naming
• No console.log (use logger)
• No commented code
• No unused imports
• Exception handling

---

9. Database

• Migration created
• Has up and down
• Kysely types updated
• Entity exported
• Repository exported

---

10. Environment

• New vars in .env.example
• Example values not real
• Use IConfigurationService, not process.env

---

Score

Weights and status (lookup):

{"weights":{"specCompliance":20,"archContract":20,"ioc":15,"restful":10,"contracts":15,"security":15,"solid":10,"quality":10,"database":5}} {"status":{"8-10":"APPROVED","6-7":"NEEDS ATTENTION","4-5":"NEEDS FIXES","0-3":"CRITICAL"}}

---

Process

Phase 1: Load Context & Create Todos

1. bash .codeadd/scripts/status.sh
2. Read reference skills (backend, database, frontend, security)
3. Read CLAUDE.md
4. Identify ALL changed files
5. Create TodoWrite (see MANDATORY RULE) covering each validation category and changed file

Phase 2: Validate

For EACH changed file, validate in order, marking each todo in_progress → completed:

1. Spec Compliance — see §1
2. Architecture Contract — see §2 (CRITICAL BLOCKER if violated; fix before continuing)
3. IoC Configuration — see §3
4. RESTful Compliance — see §4
5. Contract Validation — see §5
6. Security (OWASP) — see §6
7. SOLID Principles — see §7
8. Code Quality — see §8
9. Database — see §9

Phase 3: Fix (autopilot)

1. For each issue found:
   • Create specific todo: "Fix [issue] in [file]"
   • Mark as in_progress
   • Apply fix
   • Mark as completed
2. Verify build compiles
3. Document before/after

Phase 4: Report

Generate the review report at docs/features/${featureId}/review.md. The exact output template (score table, issue format, build status) is owned by the consuming command (add.review) — this skill validates; the command formats.

---

Rules

Do:

• Create TodoWrite BEFORE starting review and update it during each phase
• Load reference skills BEFORE review
• Run status.sh FIRST
• Auto-fix in autopilot
• Verify build
• Document before/after

Don't:

• Start review without creating TodoWrite
• Skip Architecture Contract validation (MOST critical)
• Skip IoC validation
• Report without fixing (autopilot)
• Ignore skill patterns
• Accept "works" as justification
• Leave non-compiling code
• Forget to verify AppModule.imports[] or barrel exports in libs/