cobol-java-v3/.claude/skills/code-review/references/review-checklist.md

Generic Code Review Checklist

Language-agnostic checklist covering the seven code categories across eight quality metrics. Used when no language-specific checklist matches.

---

1. Interface Layer

• All public endpoints have explicit parameter validation
• Response format is consistent across endpoints
• HTTP status codes are semantically correct (2xx success, 4xx client error, 5xx server error)
• Rate limiting considered for public-facing endpoints
• Request/response DTOs are complete (no partial exposure of internal models)
• Content-Type headers are set correctly
• Pagination implemented for list endpoints

2. Business Layer

• Business logic matches requirements (check each rule)
• State machines have all transitions defined (no impossible states)
• Idempotency designed for non-idempotent operations (create, update with side effects)
• Distributed lock usage reviewed for correctness (lock key, timeout, release)
• Business exceptions are domain-specific, not generic
• No business logic leaks into interface or data layer

3. Data Layer

• All queries use parameterized statements (no string concatenation)
• Every query has appropriate indexes (check EXPLAIN output)
• Transaction boundaries are correct (ACID where needed, rollback on error)
• No full table scans on large tables
• Batch operations used for bulk inserts/updates
• Connection pooling configured
• N+1 queries eliminated (use JOIN or batch fetch)
• Sensitive data encrypted at rest if required

4. Utility Layer

• All utility functions validate inputs
• Utility functions are pure (no side effects) unless explicitly documented
• Error states return explicit values, not null/undefined without documentation
• Date/time handling uses consistent timezone approach
• String operations handle Unicode and edge cases (empty, very long)

5. Error Handling

• Exceptions are categorized (not all caught as generic Exception/Error)
• Every external call (DB, API, file I/O) has a fallback or error boundary
• Error messages returned to clients do not leak internal details
• Retry strategy exists for transient failures (network, deadlock)
• Logging includes enough context for debugging (request ID, user, operation)
• Circuit breaker considered for critical external dependencies

6. Security

• Authentication enforced on all protected endpoints
• Authorization checked per operation, not just per endpoint
• User input validated and sanitized (XSS, injection prevention)
• Sensitive data (passwords, tokens, PII) never logged or exposed in responses
• CSRF protection for state-changing operations (if cookie-based auth)
• CORS configured restrictively, not wildcard
• Secrets (API keys, DB credentials) loaded from environment, never hardcoded
• File upload has size limits and type validation

7. Performance

• No N+1 query patterns
• Appropriate caching strategy (with invalidation logic)
• Heavy operations are async where possible
• Database queries have reasonable LIMIT clauses
• Large responses support pagination or streaming
• Connection pooling and timeouts configured
• Memory usage considered for large datasets

---

Quantitative Metrics Reference

Metric	Check
Requirement Coverage	Every requirement item mapped to ≥1 code location
Logic Alignment	Business rules implemented exactly as specified
Exception Branch Coverage	≥1 error path for every 2 happy paths (baseline)
SQL Performance Risk	No full scans on tables > 10k rows; queries have indexes
Code Redundancy Rate	< 10% of code is copy-pasted (same logic in ≥3 places)
Vulnerability Risk Rate	0 known vulnerability patterns (OWASP Top 10)
High-Risk Scenario Coverage	Concurrency, transactions, idempotency addressed for stateful ops

---

Classification Rules

• Ready: All 🔴 and 🟡 items passed. 🔵 items optional.
• Needs Fix: 🟡 items found but fixable. No 🔴 items.
• Unusable: 🔴 items found or logic fundamentally incorrect.