Software Code Review

Code Reviewing Skill — Quick Reference

This skill provides operational checklists and prompts for structured code review across languages and stacks. Use it when the primary task is reviewing existing code rather than designing new systems.

Quick Reference

---

Specialized: .NET/EF Core Crypto Integration

Skip unless reviewing C#/.NET crypto/fintech services using Entity Framework Core.

For C#/.NET crypto/fintech services using Entity Framework Core, see:

• references/dotnet-efcore-crypto-rules.md — Complete review rules (correctness, security, async, EF Core, tests, MRs)

Key rules summary:

• Review only new/modified code in the MR
• Use decimal for financial values, UTC for dates
• Follow CC-SEC-03 (no secrets in code) and CC-OBS-02 (no sensitive data in logs)
• Async for I/O, pass CancellationToken, avoid .Result/.Wait() (see CC-ERR-04, CC-FLOW-03)
• EF Core: AsNoTracking for reads, avoid N+1, no dynamic SQL
• Result<T> pattern for explicit success/fail

---

When to Use This Skill

Invoke this skill when the user asks to:

• Review a pull request or diff for issues
• Audit code for security vulnerabilities or injection risks
• Improve readability, structure, and maintainability
• Suggest targeted refactors without changing behavior
• Validate tests and edge-case coverage

When NOT to Use This Skill

• System design or architecture: Use software-architecture-design for greenfield architecture decisions
• Writing new code from scratch: This skill reviews existing code, not authoring new features
• Deep security audits: For penetration testing or comprehensive security assessments, use software-security-appsec
• Deep performance investigations: For profiling/observability, use qa-observability and for SQL/query tuning use data-sql-optimization

Decision Tree: Selecting Review Mode

Code review task: [What to Focus On?]
    ├─ Security-critical changes?
    │   ├─ Auth/access control → Security Review (OWASP, auth patterns)
    │   ├─ User input handling → Input validation, XSS, SQL injection
    │   └─ Smart contracts → Blockchain Review (reentrancy, access control)
    │
    ├─ Performance concerns?
    │   ├─ Database queries → Check for N+1, missing indexes
    │   ├─ Loops/algorithms → Complexity analysis, caching
    │   └─ API response times → Profiling, lazy loading
    │
    ├─ Correctness issues?
    │   ├─ Business logic → Edge cases, error handling, tests
    │   ├─ Data transformations → Boundary conditions, null checks
    │   └─ Integration points → Retry logic, timeouts, fallbacks
    │
    ├─ Maintainability problems?
    │   ├─ Complex code → Naming, function length, duplication
    │   ├─ Hard to understand → Comments, abstractions, clarity
    │   └─ Technical debt → Refactoring suggestions
    │
    ├─ Test coverage gaps?
    │   ├─ New features → Happy path + error cases
    │   ├─ Refactors → Regression tests
    │   └─ Bug fixes → Reproduction tests
    │
    └─ Stack-specific review?
        ├─ Frontend → [frontend-review.md](assets/web-frontend/frontend-review.md)
        ├─ Backend → [api-review.md](assets/backend-api/api-review.md)
        ├─ Mobile → [mobile-review.md](assets/mobile/mobile-review.md)
        ├─ Infrastructure → [infrastructure-review.md](assets/infrastructure/infrastructure-review.md)
        └─ Blockchain → [crypto-review.md](assets/blockchain/crypto-review.md)

Multi-Mode Reviews:

For complex PRs, apply multiple review modes sequentially:

1. Security first (P0/P1 issues) 2. Correctness (logic, edge cases) 3. Performance (if applicable) 4. Maintainability (P2/P3 suggestions)

---

Async Review Workflows (2026)

Timezone-Friendly Reviews

Non-Blocking Reviews

PR Submitted -> Auto-checks (CI) -> Async Review -> Merge
       |              |               |
  Author continues   If green,    Reviewer comments
  on other work      queue for    when available
                     review

Anti-patterns:

• Synchronous review meetings for routine PRs
• Blocking on reviewer availability for non-critical changes
• Single reviewer bottleneck

Review Prioritization Matrix

---

Optional: AI/Automation Extensions

Note: AI-assisted review tools. Human review remains authoritative.

AI Review Assistants

AI assistant rules:

• AI suggestions are advisory only
• Human reviewer approves/rejects
• AI cannot bypass security review
• AI findings require manual verification

AI Review Checklist

• [ ] AI suggestions validated against codebase patterns
• [ ] AI-flagged issues manually confirmed
• [ ] False positives documented for tool improvement
• [ ] Human reviewer explicitly approved

---

Simplicity and Complexity Control

• Prefer existing, battle-tested libraries over bespoke implementations when behavior is identical.
• Flag avoidable complexity early: remove dead/commented-out code, collapse duplication, and extract single-responsibility helpers.
• Call out premature optimization; favor clarity and measured, evidence-based tuning.
• Encourage incremental refactors alongside reviews to keep modules small, predictable, and aligned to standards.

---

Operational Playbooks

Shared Foundation

• ../software-clean-code-standard/references/clean-code-standard.md - Canonical clean code rules (CC-*) for citation in reviews
• Legacy playbook: ../software-clean-code-standard/references/code-quality-operational-playbook.md - RULE-01–RULE-13, refactoring decision trees, and design patterns

Code Review Specific

• references/operational-playbook.md — Review scope rules, severity ratings (P0-P3), checklists, modes, and PR workflow patterns

Default Review Output (Agent-Facing)

When producing a review, default to:

• Short summary of intent + risk
• Findings grouped by P0/P1/P2/P3 (mark REQUIRED vs OPTIONAL)
• Concrete suggestions (minimal diffs or test cases)
• Follow-up questions when requirements or constraints are unclear

Use assets/core/review-comment-guidelines.md for comment style and labeling.

Navigation

Resources

• references/operational-playbook.md
• references/review-checklist-comprehensive.md
• references/implementing-effective-code-reviews-checklist.md
• references/looks-good-to-me-checklist.md
• references/automation-tools.md
• references/dotnet-efcore-crypto-rules.md
• references/psychological-safety-guide.md
• references/large-pr-review-strategies.md
• references/security-focused-review-guide.md
• references/code-review-metrics.md

Templates

• assets/core/pull-request-description-template.md
• assets/core/review-checklist-judgment.md
• assets/core/review-comment-guidelines.md
• assets/backend-api/api-review.md
• assets/web-frontend/frontend-review.md
• assets/mobile/mobile-review.md
• assets/infrastructure/infrastructure-review.md
• assets/blockchain/crypto-review.md
• assets/data-ml/data-pipeline-review.md
• assets/data-ml/experiment-tracking-review.md
• assets/data-ml/ml-model-review.md
• assets/data-ml/ml-deployment-review.md

Data

• data/sources.json — Curated external references
• Shared checklists: ../software-clean-code-standard/assets/checklists/secure-code-review-checklist.md, ../software-clean-code-standard/assets/checklists/backend-api-review-checklist.md

---

Trend Awareness Protocol

IMPORTANT: When users ask recommendation questions about code review tools, practices, or automation, you MUST use WebSearch to check current trends before answering.

Trigger Conditions

• "What's the best code review tool?"
• "What should I use for [automated code review/PR automation]?"
• "What's the latest in code review practices?"
• "Current best practices for [code review/PR workflow]?"
• "Is [GitHub Copilot PR/CodeRabbit] still relevant in 2026?"
• "[CodeRabbit] vs [Graphite] vs [other]?"
• "Best AI code review assistant?"

Required Searches

1. Search: "code review best practices 2026" 2. Search: "[specific tool] vs alternatives 2026" 3. Search: "AI code review tools January 2026" 4. Search: "PR automation trends 2026"

What to Report

After searching, provide:

• Current landscape: What code review tools/practices are popular NOW
• Emerging trends: New AI assistants, PR tools, or review patterns gaining traction
• Deprecated/declining: Tools/approaches losing relevance or support
• Recommendation: Based on fresh data, not just static knowledge

Example Topics (verify with fresh search)

• AI code review (GitHub Copilot PR, CodeRabbit, Cursor)
• PR automation (Graphite, Stacked PRs, merge queues)
• Code review platforms (GitHub, GitLab, Bitbucket)
• Review bots and automation
• Async review practices for distributed teams
• Review metrics and analytics tools

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
• Prefer primary sources; report source links and dates for volatile information.
• If web access is unavailable, state the limitation and mark guidance as unverified.

Backend/API Code Review Checklist

Use this template when reviewing backend services and REST/GraphQL APIs.

Core

Standards

• Clean code standard (cite CC-* IDs): ../../../software-clean-code-standard/references/clean-code-standard.md
• Shared backend API checklist (product-agnostic): ../../../software-clean-code-standard/assets/checklists/backend-api-review-checklist.md
• Shared secure code review checklist (baseline): ../../../software-clean-code-standard/assets/checklists/secure-code-review-checklist.md

Intent & Scope

• [ ] PR description states what/why/scope; risk and rollback plan are present.
• [ ] Diff matches intent; unrelated refactors are split or explicitly justified.

API Contract

• [ ] Contract is explicit (OpenAPI/GraphQL schema) and versioning is consistent.
• [ ] Errors use a consistent model (e.g., RFC 9457 Problem Details) https://www.rfc-editor.org/rfc/rfc9457
• [ ] Idempotency and pagination are defined where needed.

Security & Privacy

• [ ] Trust boundaries are clear; authorization is enforced for every sensitive operation (cite CC-SEC-02).
• [ ] Untrusted inputs are validated and not interpolated into interpreters (cite CC-SEC-01, CC-SEC-08).
• [ ] Secrets/PII are not logged or exposed via errors (cite CC-SEC-03, CC-OBS-02, CC-ERR-02).
• [ ] Dependency posture is acceptable for the change risk (cite CC-SEC-05).

Reliability & Failure Modes

• [ ] Failure behavior is explicit and actionable (cite CC-ERR-01, CC-ERR-02).
• [ ] Retries are bounded and safe for idempotency/duplication (cite CC-ERR-03).
• [ ] I/O has timeouts and cancellation where supported (cite CC-ERR-04).
• [ ] External integrations have backoff/circuit-breaking where needed.

Data & Consistency

• [ ] Transaction boundaries are correct; invariants preserved under concurrency.
• [ ] Queries are safe and efficient (no N+1; indexes for hot predicates).
• [ ] Migrations are safe, tested, and have rollback/forward-only strategy documented.

Performance

• [ ] Work is bounded for untrusted/large inputs (cite CC-PERF-01).
• [ ] Obvious hazards avoided (N+1, O(n²) growth paths) (cite CC-PERF-02).
• [ ] Material perf changes are measured or justified in the target environment (cite CC-PERF-03).

Observability

• [ ] Logs are structured and include correlation identifiers where relevant (cite CC-OBS-01).
• [ ] Critical paths are observable (logs/metrics/traces) (cite CC-OBS-03).
• [ ] No sensitive data in logs (cite CC-OBS-02).

Tests

• [ ] New behavior is covered; bug fixes include regression tests (cite CC-TST-01).
• [ ] Tests are deterministic and isolate external dependencies (cite CC-TST-02).
• [ ] Risky changes have integration/contract tests where appropriate.

Optional: AI / Automation

• [ ] CI status checks are green and enforceable (branch protection, required checks).
• [ ] SAST/SCA/secret scanning findings reviewed; map findings to CC-* IDs when possible.
• [ ] If AI-generated code is included, validate APIs exist, align with conventions, and add tests for generated changes.
• [ ] For LLM features: explicit timeouts, cancellation, rate limits, and safe fallbacks are implemented.

Smart Contract Code Review Checklist

Comprehensive code review checklist for blockchain smart contracts (Solidity, Rust, FunC, Tact).

---

Standards (Core)

• Clean code standard (cite CC-* IDs): ../../../software-clean-code-standard/references/clean-code-standard.md
• Review comments: use labeled intent and cite CC-* IDs when applicable (../core/review-comment-guidelines.md).

Critical Security Issues (P0)

Reentrancy

• [ ] All state changes before external calls (Checks-Effects-Interactions)
• [ ] ReentrancyGuard modifier on state-changing functions
• [ ] No external calls in loops
• [ ] ETH transfers use .call{value:} with success check

Access Control

• [ ] All privileged functions have access modifiers (onlyOwner, onlyRole)
• [ ] Zero address validation on admin transfers
• [ ] Multi-signature or timelock for critical operations
• [ ] Role revocation properly implemented

Integer Overflow/Underflow

• [ ] Solidity 0.8+ or SafeMath for older versions
• [ ] unchecked blocks only where mathematically safe
• [ ] No arithmetic with user input in unchecked blocks

Oracle Manipulation

• [ ] Price data validated (not zero, not stale)
• [ ] TWAP (Time-Weighted Average Price) for critical operations
• [ ] Multiple oracle sources for redundancy
• [ ] Staleness checks (timestamp validation)
• [ ] Circuit breakers for anomalous prices

---

High Severity Issues (P1)

Frontrunning/MEV

• [ ] Commit-reveal schemes for sensitive operations
• [ ] Flashbots integration for MEV-sensitive transactions
• [ ] Slippage protection on swaps
• [ ] Deadline parameters on time-sensitive calls

Delegatecall Safety

• [ ] No delegatecall to untrusted addresses
• [ ] Proxy implementation whitelisting
• [ ] Storage collision checks in upgradeable contracts

External Call Safety

• [ ] Return values checked for all external calls
• [ ] Gas stipends appropriate (avoid .transfer() and .send())
• [ ] Reentrancy protection where needed
• [ ] Proper error handling with try/catch

Flash Loan Protection

• [ ] State changes within single transaction validated
• [ ] Balance checks at transaction end
• [ ] No reliance on balanceOf for critical logic
• [ ] Atomic invariants enforced

---

Medium Severity Issues (P2)

Gas Optimization

• [ ] Storage variables packed into 32-byte slots
• [ ] calldata used for external function arrays
• [ ] Storage reads cached in memory/stack
• [ ] Custom errors instead of require strings
• [ ] immutable and constant where applicable
• [ ] unchecked for safe arithmetic (loop counters)

Input Validation

• [ ] All user inputs validated (bounds, zero checks, array lengths)
• [ ] Address parameters checked for zero address
• [ ] Array length limits to prevent DoS
• [ ] Percentage/ratio parameters validated

Event Emission

• [ ] Events emitted for all state changes
• [ ] Indexed parameters for important values
• [ ] Events emitted before external calls
• [ ] Consistent event naming convention

Timestamp Manipulation

• [ ] No reliance on block.timestamp for short periods (<15 minutes)
• [ ] Use block.number for short time periods
• [ ] Document acceptable timestamp drift

---

Upgradeable Contract Review

Proxy Pattern Checks

• [ ] Storage gaps in base contracts (uint256[50] private __gap)
• [ ] Initializer functions protected (initializer modifier)
• [ ] Constructor disables initializers (_disableInitializers())
• [ ] No new variables before existing ones in upgrades
• [ ] _authorizeUpgrade properly protected

Storage Layout

• [ ] No storage variable reordering
• [ ] Namespaced storage for new variables
• [ ] Diamond storage pattern for complex upgrades
• [ ] Storage slot collision checks

---

DeFi-Specific Checks

AMM/DEX

• [ ] Constant product formula correct (x * y = k)
• [ ] Slippage calculation accurate
• [ ] Fee collection doesn't break invariants
• [ ] Price impact calculated correctly
• [ ] Liquidity addition/removal safe
• [ ] No rounding errors favoring attackers

Lending/Borrowing

• [ ] Collateral ratio enforced
• [ ] Liquidation threshold correct
• [ ] Health factor calculation accurate
• [ ] Interest accrual correct
• [ ] No borrowing with same asset as collateral
• [ ] Flash loan protection

Staking/Yield Farming

• [ ] Reward calculation correct
• [ ] No reward manipulation via deposits/withdrawals
• [ ] Compound interest math accurate
• [ ] Emergency withdrawal mechanism
• [ ] No loss of rewards on edge cases

---

Token-Specific Checks

ERC20

• [ ] Total supply tracking correct
• [ ] Transfer returns boolean
• [ ] Approve/TransferFrom race condition mitigated
• [ ] Decimals properly defined
• [ ] Burn/mint properly updates totalSupply

ERC721/ERC1155

• [ ] Token ID uniqueness enforced
• [ ] Metadata URI properly implemented
• [ ] Safe transfer callbacks implemented
• [ ] Batch operations safe
• [ ] Enumeration extension if needed

---

Testing Coverage

• [ ] Unit tests for all functions
• [ ] Edge case tests (zero, max uint, empty arrays)
• [ ] Access control tests (unauthorized calls fail)
• [ ] Reentrancy attack tests
• [ ] Fuzz tests with random inputs
• [ ] Fork tests for mainnet integrations
• [ ] Invariant tests for protocol properties
• [ ] Test coverage >90%
• [ ] Gas benchmarks documented

---

Documentation Review

• [ ] NatSpec comments on all public/external functions
• [ ] Architecture diagrams present
• [ ] Known limitations documented
• [ ] Upgrade procedure documented
• [ ] Emergency procedures defined
• [ ] Deployment checklist complete

---

Deployment Preparation

• [ ] No floating pragma (version locked)
• [ ] Compiler warnings addressed
• [ ] Optimizer runs configured appropriately
• [ ] Contract verified on block explorer
• [ ] Multi-sig wallet as owner
• [ ] Timelock for critical operations
• [ ] Monitoring and alerting configured
• [ ] Professional audit completed
• [ ] Bug bounty program prepared

---

Solana-Specific Checks (Rust/Anchor)

Account Validation

• [ ] All accounts validated (ownership, signer, mutability)
• [ ] PDA (Program Derived Address) seeds validated
• [ ] Account discriminators checked
• [ ] Account size constraints enforced

Signer Checks

• [ ] Required signers properly enforced
• [ ] No missing is_signer constraints
• [ ] Authority validation on privileged operations

CPI (Cross-Program Invocation)

• [ ] CPI signer seeds validated
• [ ] Program ID validation
• [ ] Account ownership validated post-CPI

---

TON-Specific Checks (FunC/Tact)

Message Handling

• [ ] Bounce flag properly set
• [ ] Message value validation
• [ ] Excess gas refunded
• [ ] Internal message handling correct

State Management

• [ ] Persistent data properly saved
• [ ] Cell references valid
• [ ] Gas limits appropriate

---

Clean Code (Core)

• Standards: cite CC-* IDs; do not restate rules.
• Common CC-* IDs for contracts: CC-NAM-01, CC-FUN-01, CC-FUN-05, CC-FLOW-03, CC-ERR-01, CC-ERR-02, CC-TYP-04, CC-DOC-01, CC-DOC-04, CC-TST-01

---

Review Process (Core)

1. Manual Review:

• Read contract line-by-line
• Check against this checklist
• Verify test coverage
• Review deployment scripts

2. Testing:

• Run all unit tests
• Run fork tests if applicable
• Verify gas costs
• Check coverage reports

3. Documentation Review:

• Verify NatSpec completeness
• Check README accuracy
• Validate deployment guide

---

Severity Ratings

• P0 (Critical): Funds at risk, immediate exploit possible
• P1 (High): Security vulnerability, complex exploit
• P2 (Medium): Logic error, gas inefficiency, poor UX
• P3 (Low): Code quality, best practices, documentation

---

Common Anti-Patterns to Avoid

// BAD: Using tx.origin for authorization
require(tx.origin == owner);

// BAD: Unprotected ether transfer
payable(msg.sender).transfer(amount);

// BAD: Reentrancy vulnerability
balances[msg.sender] -= amount;
msg.sender.call{value: amount}("");

// BAD: Unprotected self-destruct
selfdestruct(payable(owner));

// BAD: Floating pragma
pragma solidity ^0.8.0;

// BAD: Missing access control
function mint(address to, uint amount) public {
    _mint(to, amount);
}

---

Optional: AI / Automation

• Automated analysis: Slither/Mythril/Manticore; lint rules (Solhint/Ethlint) where relevant.
• Fuzzing and invariants: Echidna, Foundry invariant tests.
• Formal verification (when warranted): Certora Prover, K Framework.
• Monitoring/defense in depth: Tenderly, OpenZeppelin Defender.

Pull Request Description Template

Core

Summary (What)

Motivation (Why)

Scope

• In:
• Out:

Risk

• Priority: P0 / P1 / P2 / P3
• Blast radius:
• Rollback plan:

Verification

• Tests run:
• Manual checks:

Operability

• Logs/metrics/traces:
• Alerts/runbooks impacted:

Reviewer Notes

• Areas to focus:
• Follow-ups:
• Links:

Optional: AI / Automation

• CI checks and status checks:
• CODEOWNERS / required reviewers:
• Automation findings mapped to CC-* IDs:

Review Checklist (Judgment-Based)

Core

• Intent: PR description explains what and why; diff matches intent (https://google.github.io/eng-practices/review/developer/cl-descriptions.html).
• Size: if too large to review effectively, request a split (https://google.github.io/eng-practices/review/developer/small-cls.html).
• Correctness: walk the happy path, key error paths, and boundaries.
• Risk: identify blast radius, rollout/rollback, and migration risk if applicable.
• Security/privacy: confirm trust boundaries, authz checks, and safe data handling.
• Operability: confirm diagnosability (logs/metrics/traces) for critical paths (https://opentelemetry.io/docs/).
• Tests: new behavior has tests; bug fixes have regression tests.
• Standards: cite CC-* IDs from the clean code standard; do not restate rules (../../../software-clean-code-standard/references/clean-code-standard.md).

Optional: AI / Automation

• CI is green and branch protection rules are enforced (https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches).
• Review routing uses CODEOWNERS where appropriate (https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
• Automation output (linters/SAST/SCA) is mapped to CC-* IDs when possible.
• AI suggestions are advisory only; human reviewers validate and approve.

Review Comment Guidelines

Core

• Use labeled intent for comments (issue/suggestion/question/nitpick/praise) (https://conventionalcomments.org/).
• Mark blocking vs non-blocking clearly.
• If a comment is about clean code standards, cite the CC-* rule ID (../../../software-clean-code-standard/references/clean-code-standard.md).
• Prefer actionable feedback: propose a concrete change, a minimal example, or a specific question.
• Avoid style debates and purely preference-based rewrites; rely on the standard and automation.
• Keep feedback specific and behavior-focused; avoid personal language (see references/psychological-safety-guide.md).

Optional: AI / Automation

• If using automated review tools, validate findings before posting; treat false positives as tuning input.
• Where possible, configure tools to emit CC-* IDs to keep feedback consistent.

Data Pipeline Code Review Checklist

Specialized checklist for reviewing data processing pipelines, ETL/ELT workflows, and feature engineering pipelines.

---

Pipeline Architecture

Design Principles

• [ ] Pipeline purpose and scope clearly defined
• [ ] Data flow diagram documented
• [ ] Input/output contracts specified
• [ ] Pipeline stages logically separated
• [ ] Idempotency ensured (can re-run safely)
• [ ] Incremental processing strategy defined

Orchestration

• [ ] Orchestration tool appropriate (Airflow, Prefect, Dagster, etc.)
• [ ] DAG structure clear and logical
• [ ] Dependencies explicitly defined
• [ ] Task granularity appropriate
• [ ] Parallel execution opportunities identified
• [ ] Critical path optimized

Scalability

• [ ] Data volume growth considered
• [ ] Processing strategy scales (batch vs streaming)
• [ ] Resource requirements documented
• [ ] Bottlenecks identified and addressed
• [ ] Partitioning strategy defined

---

Data Ingestion

Source Integration

• [ ] Data sources documented (APIs, databases, files)
• [ ] Authentication/authorization handled securely
• [ ] Rate limiting respected
• [ ] Connection pooling configured
• [ ] Retry logic with exponential backoff
• [ ] Timeout settings appropriate

Data Extraction

• [ ] Incremental loading strategy defined
• [ ] Full refresh vs incremental logic clear
• [ ] Watermarks/checkpoints tracked
• [ ] Change data capture (CDC) if applicable
• [ ] Deleted records handled
• [ ] Schema evolution handled

Error Handling

• [ ] Transient failures retried appropriately
• [ ] Permanent failures logged and alerted
• [ ] Partial failures don't block entire pipeline
• [ ] Dead letter queue for failed records
• [ ] Circuit breaker pattern for flaky sources

---

Data Validation

Schema Validation

• [ ] Input schema validated on ingestion
• [ ] Column types enforced
• [ ] Required fields checked
• [ ] Schema drift detected
• [ ] Schema versions tracked
• [ ] Breaking changes prevented

Data Quality Checks

• [ ] Null/missing value checks
• [ ] Range/bound checks on numeric fields
• [ ] Format validation on strings/dates
• [ ] Referential integrity checks
• [ ] Duplicate detection
• [ ] Anomaly detection for data distribution

Business Logic Validation

• [ ] Domain-specific rules validated
• [ ] Cross-field consistency checked
• [ ] Business constraints enforced
• [ ] Data completeness verified
• [ ] Thresholds for acceptable data quality defined

---

Data Transformation

Transformation Logic

• Baseline CC-* to apply (cite IDs if violated): CC-DOC-01, CC-FUN-01, CC-FUN-04, CC-TYP-04, CC-NAM-03
• [ ] Timezone handling explicit
• [ ] Date/time arithmetic correct

Feature Engineering

• [ ] Feature transformations reproducible
• [ ] No train/serve skew in features
• [ ] Feature statistics computed from training data only
• [ ] Feature store integration (if applicable)
• [ ] Feature versioning tracked
• [ ] No data leakage in feature creation

Performance Optimization

• [ ] Efficient SQL queries (proper joins, filters, indexes)
• [ ] Data shuffles minimized
• [ ] Unnecessary computations eliminated
• [ ] Caching used for expensive operations
• [ ] Broadcast joins for small tables (Spark)
• [ ] Partitioning strategy optimized

---

Data Storage

Storage Strategy

• [ ] Storage format appropriate (Parquet, Delta, Iceberg, etc.)
• [ ] Partitioning scheme efficient
• [ ] Compression enabled
• [ ] Data lifecycle policy defined
• [ ] Cold storage strategy for old data
• [ ] Retention periods documented

Data Organization

• [ ] Staging/intermediate/marts layers clear
• [ ] Naming is consistent and intention-revealing (cite CC-NAM-01, CC-NAM-02, CC-NAM-03)
• [ ] Directory structure logical
• [ ] Metadata tracked (lineage, timestamps, versions)
• [ ] Access controls configured

Data Versioning

• [ ] Data versions tracked
• [ ] Snapshots available for reproducibility
• [ ] Rollback strategy defined
• [ ] Version compatibility documented

---

Monitoring & Observability

Pipeline Monitoring

• [ ] Pipeline execution metrics tracked
• [ ] Processing duration monitored
• [ ] Record counts logged
• [ ] Success/failure rates tracked
• [ ] Resource utilization monitored (CPU, memory, I/O)

Data Monitoring

• [ ] Data volume trends tracked
• [ ] Data quality metrics computed
• [ ] Schema changes detected
• [ ] Distribution shifts detected (data drift)
• [ ] Missing data alerts configured

Alerting

• [ ] Critical failures trigger alerts
• [ ] Data quality violations trigger alerts
• [ ] SLA breaches trigger alerts
• [ ] Alert fatigue avoided (appropriate thresholds)
• [ ] Runbook linked to alerts

---

Testing

Unit Tests

• [ ] Transformation functions unit tested
• [ ] Edge cases covered
• [ ] Null handling tested
• [ ] Data type conversions tested
• [ ] Business logic validated

Integration Tests

• [ ] End-to-end pipeline tested on sample data
• [ ] Source connections tested
• [ ] Destination writes tested
• [ ] Error handling paths tested
• [ ] Rollback tested

Data Tests

• [ ] Expected schema tests
• [ ] Row count tests
• [ ] Uniqueness tests
• [ ] Non-null tests
• [ ] Referential integrity tests
• [ ] Regression tests for known issues

---

Error Handling & Recovery

Failure Modes

• [ ] Transient vs permanent failures distinguished
• [ ] Retry logic with exponential backoff
• [ ] Max retry limits defined
• [ ] Circuit breaker for repeated failures
• [ ] Graceful degradation where possible

Recovery Mechanisms

• [ ] Checkpoint/resume capability
• [ ] Idempotent operations (safe to re-run)
• [ ] Rollback procedures documented
• [ ] Manual intervention triggers clear
• [ ] Data reconciliation after failures

Logging

• [ ] Structured logging used
• [ ] Log levels appropriate (DEBUG, INFO, WARN, ERROR)
• [ ] Sensitive data not logged
• [ ] Correlation IDs for tracing
• [ ] Logs retained per policy

---

Security & Privacy

Data Security

• [ ] Data encrypted in transit (TLS)
• [ ] Data encrypted at rest (where required)
• [ ] Access controls enforced (IAM, RBAC)
• [ ] Secrets managed securely (vault, env vars)
• [ ] No credentials in code or logs
• [ ] Audit logs enabled

Privacy Compliance

• [ ] PII identified and classified
• [ ] Data anonymization/pseudonymization applied
• [ ] Data retention policies followed
• [ ] Right to deletion supported
• [ ] Compliance requirements documented (GDPR, CCPA, etc.)
• [ ] Data lineage tracked for audits

Data Governance

• [ ] Data ownership documented
• [ ] Data classification applied
• [ ] Access requests logged
• [ ] Data sharing agreements followed
• [ ] Compliance audits supported

---

Clean Code (Core)

• Clean code standard (cite CC-* IDs): ../../../software-clean-code-standard/references/clean-code-standard.md
• Standards: cite CC-* IDs; do not restate rules.
• Common CC-* IDs for data pipelines: CC-NAM-01, CC-NAM-03, CC-FUN-01, CC-FUN-05, CC-TYP-01, CC-TYP-04, CC-ERR-01, CC-ERR-04, CC-SEC-03, CC-SEC-05, CC-DOC-01, CC-DOC-04, CC-TST-01

Configuration Management

• [ ] Configuration is externalized (not hardcoded) and environment differences are explicit.
• [ ] Configuration is validated on startup; defaults are safe for production.

Documentation

• [ ] Pipeline purpose and contracts documented (inputs, outputs, failure modes).
• [ ] Setup and troubleshooting steps are clear; runbook exists for on-call.

---

Performance & Efficiency

Resource Utilization

• [ ] Memory usage optimized (lazy loading, chunking)
• [ ] CPU utilization efficient
• [ ] Network I/O minimized
• [ ] Disk I/O minimized
• [ ] Parallelization used where beneficial

Cost Optimization

• [ ] Compute resources right-sized
• [ ] Storage costs optimized (compression, lifecycle)
• [ ] Spot/preemptible instances used where appropriate
• [ ] Cost monitoring enabled
• [ ] Cost budget alerts configured

Latency Optimization

• [ ] Pipeline duration meets SLA
• [ ] Critical path optimized
• [ ] Unnecessary dependencies eliminated
• [ ] Caching used for repeated computations
• [ ] Data locality optimized (avoid shuffles)

---

Production Readiness

Deployment

• [ ] CI/CD pipeline configured
• [ ] Automated testing in CI
• [ ] Deployment strategy defined (blue/green, canary)
• [ ] Rollback procedure documented
• [ ] Environment parity (dev/staging/prod)

Maintenance

• [ ] Monitoring dashboards created
• [ ] Alert rules configured
• [ ] Runbook complete
• [ ] On-call rotation defined
• [ ] Incident response process documented

Documentation

• [ ] Architecture diagram available
• [ ] Data dictionary maintained
• [ ] SLA/SLO documented
• [ ] Owners and contacts listed
• [ ] Handover documentation complete

---

SQLMesh Specific (if applicable)

Model Configuration

• [ ] Model types appropriate (FULL, INCREMENTAL_BY_TIME_RANGE, etc.)
• [ ] Incremental strategy correct
• [ ] Partitioning aligned with incremental key
• [ ] Dependencies (ref()) correct
• [ ] Model descriptions provided

Testing & Validation

• [ ] Unit tests for model logic
• [ ] Audits for data quality
• [ ] CI/CD integration configured
• [ ] Test data fixtures provided

Best Practices

• [ ] Staging/intermediate/marts layers clear
• [ ] Incremental models for large tables
• [ ] Backfill strategy defined
• [ ] Environment promotion workflow

---

Final Checklist

Before approving data pipeline code:

• [ ] Pipeline runs successfully end-to-end
• [ ] Data quality checks passing
• [ ] Tests passing
• [ ] Monitoring and alerting configured
• [ ] Documentation complete
• [ ] Security and privacy reviewed
• [ ] Production deployment plan reviewed

Experiment Tracking Code Review Checklist

Specialized checklist for reviewing ML experiment tracking implementations (MLflow, Weights & Biases, Neptune, etc.).

---

Experiment Configuration

Metadata Tracking

• [ ] Experiment name descriptive and consistent
• [ ] Run names unique and informative
• [ ] Tags used for categorization
• [ ] Git commit hash tracked
• [ ] User/author information logged
• [ ] Timestamp recorded

Hyperparameters

• [ ] All hyperparameters logged
• [ ] Hyperparameter names consistent across runs
• [ ] Nested hyperparameters structured properly
• [ ] Default values documented
• [ ] Hyperparameter search space tracked

Environment Information

• [ ] Python/package versions logged
• [ ] Hardware specs recorded (CPU, GPU, memory)
• [ ] Operating system logged
• [ ] Random seeds documented
• [ ] Environment reproducibility ensured

---

Data Versioning

Dataset Tracking

• [ ] Training data version/snapshot ID logged
• [ ] Validation data version logged
• [ ] Test data version logged
• [ ] Data source and location documented
• [ ] Data size and statistics logged
• [ ] Data hash/checksum recorded

Feature Tracking

• [ ] Feature set version tracked
• [ ] Feature list documented
• [ ] Feature transformations logged
• [ ] Feature importance tracked (if applicable)
• [ ] Feature store integration (if applicable)

Data Quality

• [ ] Data quality metrics logged
• [ ] Missing value statistics recorded
• [ ] Distribution statistics logged
• [ ] Outlier detection results tracked
• [ ] Data drift metrics logged

---

Model Tracking

Model Artifacts

• [ ] Trained model saved
• [ ] Model format standardized
• [ ] Model size tracked
• [ ] Model architecture logged
• [ ] Preprocessing pipeline saved with model
• [ ] Model versioning consistent

Model Metadata

• [ ] Model type/family documented
• [ ] Number of parameters logged
• [ ] Training duration recorded
• [ ] Compute resources used documented
• [ ] Model registry entry created

Model Dependencies

• [ ] Framework versions logged (PyTorch, TensorFlow, scikit-learn)
• [ ] Custom code/modules tracked
• [ ] External dependencies documented
• [ ] Model can be loaded independently

---

Metrics & Performance

Training Metrics

• [ ] Loss curves logged (train and validation)
• [ ] Metrics logged at appropriate intervals
• [ ] Learning rate schedule logged
• [ ] Gradient norms tracked (if neural network)
• [ ] Training convergence monitored

Evaluation Metrics

• [ ] Primary metric logged
• [ ] Guardrail metrics logged
• [ ] Metrics calculated on held-out test set
• [ ] Baseline performance documented
• [ ] Metric definitions standardized

Slice Analysis

• [ ] Performance by slice tracked
• [ ] Fairness metrics logged
• [ ] Error analysis results documented
• [ ] Weak segment performance highlighted

---

Artifacts & Visualizations

Plots & Charts

• [ ] Loss curves saved
• [ ] Confusion matrices logged
• [ ] ROC/PR curves saved
• [ ] Feature importance plots logged
• [ ] Error distribution plots saved
• [ ] Calibration plots logged (if applicable)

Reports & Documents

• [ ] Model evaluation report attached
• [ ] Model card created/linked
• [ ] Experiment notes documented
• [ ] Known issues/limitations recorded
• [ ] Next steps/recommendations logged

Code Artifacts

• [ ] Training script saved
• [ ] Configuration files saved
• [ ] Preprocessing code saved
• [ ] Evaluation code saved

---

Experiment Organization

Naming Conventions

• [ ] Experiment names follow convention
• [ ] Run names informative and consistent
• [ ] Tags used systematically
• [ ] Folder/project structure logical
• [ ] Naming conflicts avoided

Grouping & Filtering

• [ ] Related experiments grouped
• [ ] Hyperparameter sweeps organized
• [ ] Ablation studies clearly marked
• [ ] Easy to filter by key attributes
• [ ] Parent-child run relationships tracked

Search & Discovery

• [ ] Experiments searchable by hyperparameters
• [ ] Experiments filterable by metrics
• [ ] Experiments sortable by performance
• [ ] Best runs easily identifiable
• [ ] Failed runs marked appropriately

---

Reproducibility

Code Versioning

• [ ] Git commit tracked
• [ ] Code snapshot saved (if no git)
• [ ] Branch name logged
• [ ] Uncommitted changes flagged
• [ ] Code diff tracked for important changes

Environment Reproducibility

• [ ] Requirements.txt/environment.yml saved
• [ ] Docker image tag logged (if applicable)
• [ ] Conda environment exported
• [ ] System dependencies documented

Data Reproducibility

• [ ] Data version pinned
• [ ] Data preprocessing steps tracked
• [ ] Random seeds set and logged
• [ ] Deterministic operations ensured
• [ ] Non-deterministic operations flagged

Re-run Capability

• [ ] Experiment can be re-run from logs
• [ ] Results reproducible within noise
• [ ] Instructions clear for reproduction
• [ ] All dependencies documented

---

Comparison & Analysis

Run Comparison

• [ ] Comparison views easy to create
• [ ] Hyperparameter differences highlighted
• [ ] Metric differences visualized
• [ ] Statistical significance tested
• [ ] Best run selection criteria clear

Hyperparameter Optimization

• [ ] Optimization strategy logged (grid, random, Bayesian)
• [ ] Search space documented
• [ ] Optimization progress tracked
• [ ] Best hyperparameters identified
• [ ] Convergence of optimization monitored

Ablation Studies

• [ ] Ablation experiments clearly marked
• [ ] Component removal tracked
• [ ] Impact on performance quantified
• [ ] Conclusions documented

---

Integration & Automation

CI/CD Integration

• [ ] Experiments logged in automated pipelines
• [ ] Training metrics published to CI system
• [ ] Model registration automated
• [ ] Failed experiments flagged in CI
• [ ] Experiment dashboard linked from CI

Model Registry Integration

• [ ] Models registered automatically
• [ ] Model stage transitions logged (staging, production)
• [ ] Model lineage tracked (experiment → registry)
• [ ] Model annotations consistent
• [ ] Deployment metadata linked

Orchestration Integration

• [ ] Experiments logged from orchestrator (Airflow, etc.)
• [ ] Task parameters logged
• [ ] Execution context captured
• [ ] Orchestrator run ID linked

---

Monitoring & Alerting

Experiment Monitoring

• [ ] Long-running experiments monitored
• [ ] Stalled experiments detected
• [ ] Resource utilization tracked
• [ ] Cost tracking enabled
• [ ] Training anomalies detected

Performance Tracking

• [ ] Performance trends visualized
• [ ] Performance degradation detected
• [ ] Comparison to baseline automated
• [ ] Alerts configured for key metrics

Collaborative Features

• [ ] Experiment notes/comments enabled
• [ ] Team members tagged where relevant
• [ ] Shared dashboards created
• [ ] Experiment reviews tracked

---

Security & Privacy

Access Control

• [ ] Experiments visible to appropriate teams
• [ ] Sensitive experiments access-controlled
• [ ] API keys/tokens managed securely
• [ ] Audit logs enabled

Data Privacy

• [ ] No PII logged in experiments
• [ ] Sensitive metrics redacted
• [ ] Data samples anonymized
• [ ] Compliance requirements met

Secrets Management

• [ ] No credentials in logged config
• [ ] Environment variables used for secrets
• [ ] API keys rotated regularly
• [ ] Access tokens time-limited

---

Clean Code (Core)

• Clean code standard (cite CC-* IDs): ../../../software-clean-code-standard/references/clean-code-standard.md
• Standards: cite CC-* IDs; do not restate rules.
• Common CC-* IDs for experiment tracking: CC-OBS-01, CC-OBS-02, CC-OBS-03, CC-ERR-01, CC-ERR-03, CC-ERR-04, CC-PERF-01, CC-PERF-02, CC-FUN-05, CC-TST-01, CC-DOC-01

Testing

• [ ] Unit tests for logging functions
• [ ] Integration tests with experiment tracker
• [ ] Mock logging in unit tests
• [ ] Logging failures don't crash training

Performance

• [ ] Logging async where possible
• [ ] Batch logging used for high-frequency metrics
• [ ] Network retries configured
• [ ] Logging overhead minimized

---

Documentation

Experiment Documentation

• [ ] Purpose of experiment clear
• [ ] Hypotheses documented
• [ ] Methodology explained
• [ ] Results interpreted
• [ ] Lessons learned captured

Team Documentation

• [ ] Team conventions documented
• [ ] Naming standards defined
• [ ] Tagging guidelines provided
• [ ] Dashboard templates available
• [ ] Onboarding guide for new team members

External Documentation

• [ ] Experiment tracker setup documented
• [ ] Authentication setup instructions clear
• [ ] API usage examples provided
• [ ] Troubleshooting guide available

---

MLflow Specific (if applicable)

Tracking Setup

• [ ] Tracking URI configured correctly
• [ ] Backend store configured (database, file)
• [ ] Artifact store configured (S3, Azure, etc.)
• [ ] Authentication enabled
• [ ] Multi-user setup if needed

Model Registry

• [ ] Models registered with meaningful names
• [ ] Model versions tracked
• [ ] Model stages used appropriately
• [ ] Model annotations/tags used
• [ ] Model lineage clear

Projects & Models

• [ ] MLflow Projects used for reproducibility
• [ ] MLproject file complete
• [ ] Environment specification included
• [ ] Model flavor appropriate
• [ ] Custom models logged correctly

---

Weights & Biases Specific (if applicable)

Logging Features

• [ ] wandb.init() called appropriately
• [ ] wandb.config for hyperparameters
• [ ] wandb.log() for metrics
• [ ] wandb.watch() for model tracking
• [ ] wandb.finish() called on completion

Visualizations

• [ ] wandb.Image() for image logging
• [ ] wandb.Table() for data logging
• [ ] Custom charts configured
• [ ] Reports created for key experiments

Collaboration

• [ ] Team/project structure appropriate
• [ ] Artifacts shared with team
• [ ] Report links in documentation
• [ ] Comments/notes used for collaboration

---

Final Checklist

Before approving experiment tracking code:

• [ ] All experiments reproducible
• [ ] Metrics and hyperparameters logged completely
• [ ] Model artifacts saved correctly
• [ ] Code and data versions tracked
• [ ] Documentation clear and complete
• [ ] Team conventions followed
• [ ] Integration with downstream systems working

ML Deployment Code Review Checklist

Specialized checklist for reviewing ML model deployment code (serving, APIs, batch inference, monitoring).

---

Deployment Architecture

Service Design

• [ ] Deployment type appropriate (real-time API, batch, streaming)
• [ ] Architecture diagram documented
• [ ] Scalability strategy defined
• [ ] High availability considerations addressed
• [ ] Disaster recovery plan documented

Model Serving

• [ ] Serving framework appropriate (FastAPI, TorchServe, TensorFlow Serving, BentoML, etc.)
• [ ] Model loading strategy defined
• [ ] Model versioning supported
• [ ] A/B testing capability (if needed)
• [ ] Canary deployment supported
• [ ] Blue/green deployment possible

Infrastructure

• [ ] Compute resources right-sized
• [ ] Auto-scaling configured
• [ ] Load balancing configured
• [ ] Health checks implemented
• [ ] Resource limits set (CPU, memory, GPU)

---

API Design (Real-Time Serving)

Request/Response Contract

• [ ] Input schema clearly defined
• [ ] Output schema clearly defined
• [ ] Versioned API endpoints (/v1/, /v2/)
• [ ] Request validation comprehensive
• [ ] Response format consistent
• [ ] Error responses standardized

Endpoint Implementation

• [ ] RESTful design principles followed
• [ ] HTTP methods appropriate (POST for predictions)
• [ ] Status codes correct (200, 400, 500, 503)
• [ ] Request size limits enforced
• [ ] Timeout settings appropriate
• [ ] Pagination for batch predictions

API Documentation

• [ ] OpenAPI/Swagger documentation generated
• [ ] Example requests/responses provided
• [ ] Error codes documented
• [ ] Rate limits documented
• [ ] Authentication requirements clear

---

Model Lifecycle

Model Loading

• [ ] Model loaded efficiently on startup
• [ ] Lazy loading for large models (if needed)
• [ ] Model preloaded to avoid cold start
• [ ] Model loading errors handled gracefully
• [ ] Model format validated on load

Model Updates

• [ ] Hot-swapping supported (if needed)
• [ ] Model version managed explicitly
• [ ] Rollback mechanism implemented
• [ ] Zero-downtime updates possible
• [ ] Model registry integration

Model Caching

• [ ] Models cached in memory appropriately
• [ ] Cache eviction policy defined
• [ ] Multiple model versions supported
• [ ] Cache warming strategy

---

Preprocessing & Postprocessing

Input Preprocessing

• [ ] Preprocessing matches training pipeline
• [ ] Train-serve skew prevented
• [ ] Feature transformations correct
• [ ] Missing value handling consistent
• [ ] Input validation comprehensive

Feature Engineering

• [ ] Features computed identically to training
• [ ] Feature store integration (if applicable)
• [ ] Feature versioning tracked
• [ ] Real-time feature computation optimized
• [ ] Feature lag handled correctly

Output Postprocessing

• [ ] Predictions transformed to business-friendly format
• [ ] Probability calibration applied (if needed)
• [ ] Thresholds applied correctly
• [ ] Output validation performed
• [ ] Explanation/interpretation provided (if needed)

---

Performance & Latency

Inference Optimization

• [ ] Batch inference used where possible
• [ ] Model quantization applied (if applicable)
• [ ] GPU utilization optimized
• [ ] Model compiled/optimized (TorchScript, ONNX, TensorRT)
• [ ] Unnecessary computation eliminated

Latency Requirements

• [ ] Latency SLA defined and measured
• [ ] P50, P95, P99 latencies tracked
• [ ] Timeout settings appropriate
• [ ] Slow predictions logged and analyzed
• [ ] Performance benchmarks documented

Throughput

• [ ] Throughput requirements defined
• [ ] Concurrent request handling optimized
• [ ] Request queuing strategy defined
• [ ] Rate limiting configured
• [ ] Load testing performed

---

Batch Inference

Batch Processing

• [ ] Batch size optimized for throughput
• [ ] Parallelization strategy defined
• [ ] Partitioning for distributed processing
• [ ] Progress tracking implemented
• [ ] Resumability for long-running jobs

Data I/O

• [ ] Efficient data loading (lazy, streaming)
• [ ] Output writing optimized (batched writes)
• [ ] File formats efficient (Parquet, etc.)
• [ ] Data partitioning strategy
• [ ] Temporary files cleaned up

Orchestration

• [ ] Batch job scheduling defined
• [ ] Dependencies managed (Airflow, etc.)
• [ ] Retry logic for failed batches
• [ ] Monitoring and alerting configured
• [ ] Cost optimization considered

---

Monitoring & Observability

Performance Monitoring

• [ ] Latency metrics tracked (P50, P95, P99)
• [ ] Throughput metrics tracked
• [ ] Error rate monitored
• [ ] Resource utilization monitored (CPU, memory, GPU)
• [ ] Queue depth monitored

Model Performance

• [ ] Prediction distribution tracked
• [ ] Data drift detection enabled
• [ ] Model drift detection enabled
• [ ] Performance degradation alerts
• [ ] Comparison to baseline automated

Business Metrics

• [ ] Business KPIs tracked
• [ ] Prediction impact measured
• [ ] A/B test results tracked
• [ ] ROI/value metrics computed

Logging

• [ ] Structured logging used
• [ ] Request/response logged (with sampling)
• [ ] Predictions logged for debugging
• [ ] Model version logged per request
• [ ] Correlation IDs for tracing

---

Error Handling & Reliability

Error Handling

• [ ] All error paths handled explicitly
• [ ] User-facing errors informative
• [ ] Internal errors logged with context
• [ ] No silent failures
• [ ] Graceful degradation where possible

Fallback Strategies

• [ ] Fallback model available (if needed)
• [ ] Default predictions for edge cases
• [ ] Circuit breaker for failing models
• [ ] Retry logic with exponential backoff
• [ ] Timeout handling appropriate

Data Validation

• [ ] Input data validated before inference
• [ ] Out-of-range values handled
• [ ] Missing features handled
• [ ] Unexpected data types rejected
• [ ] Malformed requests rejected with clear errors

---

Security

Authentication & Authorization

• [ ] API authentication required
• [ ] Token validation implemented
• [ ] Rate limiting per user/API key
• [ ] Authorization checks on sensitive predictions
• [ ] API keys rotated regularly

Input Validation

• [ ] Input sanitization to prevent injection
• [ ] Input size limits enforced
• [ ] Malicious input detection
• [ ] DDoS protection configured
• [ ] SSRF prevention

Data Privacy

• [ ] PII handling compliant with regulations
• [ ] Predictions not logged with PII (or anonymized)
• [ ] Data retention policy enforced
• [ ] Encryption in transit (TLS)
• [ ] Encryption at rest (if required)

Model Security

• [ ] Model files access-controlled
• [ ] Model intellectual property protected
• [ ] Adversarial input detection (if applicable)
• [ ] Model extraction attacks considered
• [ ] Inference-time attacks mitigated

---

Testing

Unit Tests

• [ ] Preprocessing functions tested
• [ ] Postprocessing functions tested
• [ ] Input validation tested
• [ ] Model loading tested
• [ ] Error handling paths tested

Integration Tests

• [ ] End-to-end API tests
• [ ] Model inference tests on sample data
• [ ] Error response tests
• [ ] Timeout tests
• [ ] Load tests

Model Validation Tests

• [ ] Model output sanity checks
• [ ] Model predictions within expected range
• [ ] Model consistency checks (same input → same output)
• [ ] Regression tests (predictions match baseline)
• [ ] Slice-based validation tests

---

Deployment Pipeline

CI/CD Integration

• [ ] Automated testing in CI
• [ ] Model validation checks automated
• [ ] Deployment pipeline defined
• [ ] Canary deployment strategy
• [ ] Rollback procedure automated

Environment Management

• [ ] Dev/staging/prod environments
• [ ] Environment parity maintained
• [ ] Configuration per environment
• [ ] Infrastructure as code (Terraform, etc.)
• [ ] Secrets management (Vault, AWS Secrets Manager)

Versioning

• [ ] Model version tracked per deployment
• [ ] API version tracked
• [ ] Code version tracked (git tag)
• [ ] Deployment history maintained
• [ ] Rollback to previous version possible

---

Scalability & Reliability

Horizontal Scaling

• [ ] Stateless service design
• [ ] Auto-scaling rules configured
• [ ] Load balancer configured
• [ ] Session affinity not required
• [ ] Distributed caching (if needed)

High Availability

• [ ] Multi-instance deployment
• [ ] Health checks configured
• [ ] Graceful shutdown implemented
• [ ] Circuit breaker pattern
• [ ] Retry logic for transient failures

Resource Management

• [ ] Resource limits enforced
• [ ] Memory leaks prevented
• [ ] Connection pooling configured
• [ ] Garbage collection tuned (if applicable)
• [ ] GPU memory managed efficiently

---

Cost Optimization

Compute Efficiency

• [ ] Right-sized instances for workload
• [ ] Spot/preemptible instances used (batch)
• [ ] Auto-scaling for cost optimization
• [ ] Idle resources scaled down
• [ ] GPU usage justified and optimized

Cost Monitoring

• [ ] Cost per prediction tracked
• [ ] Cost budget alerts configured
• [ ] Cost trends monitored
• [ ] Cost allocation by model/team
• [ ] Cost optimization opportunities identified

---

Documentation & Handover

Deployment Documentation

• [ ] Architecture diagram available
• [ ] Deployment steps documented
• [ ] Configuration guide provided
• [ ] Environment setup instructions
• [ ] Dependencies documented

Operational Runbook

• [ ] Monitoring dashboard links provided
• [ ] Alert definitions documented
• [ ] Troubleshooting guide available
• [ ] Rollback procedure documented
• [ ] Escalation process defined

Model Documentation

• [ ] Model card available
• [ ] Input/output contract documented
• [ ] Performance SLA documented
• [ ] Known limitations listed
• [ ] Model version and lineage tracked

Maintenance

• [ ] Owners and contacts listed
• [ ] On-call rotation defined
• [ ] Incident response process documented
• [ ] Retraining schedule defined
• [ ] Maintenance windows planned

---

Compliance & Governance

Regulatory Compliance

• [ ] GDPR/CCPA compliance verified
• [ ] Data residency requirements met
• [ ] Audit logs enabled
• [ ] Right to explanation supported (if applicable)
• [ ] Model bias and fairness assessed

Model Governance

• [ ] Model approval process followed
• [ ] Model risk assessment completed
• [ ] Model documentation complete
• [ ] Model monitoring plan approved
• [ ] Model retirement plan defined

Change Management

• [ ] Change requests documented
• [ ] Impact analysis performed
• [ ] Stakeholder approval obtained
• [ ] Communication plan executed
• [ ] Post-deployment review scheduled

---

Final Checklist

Before approving ML deployment code:

• [ ] Deployment architecture reviewed and approved
• [ ] Performance meets SLA requirements
• [ ] Security review completed
• [ ] Tests passing (unit, integration, load)
• [ ] Monitoring and alerting configured
• [ ] Documentation complete
• [ ] Rollback procedure tested
• [ ] Production readiness checklist completed

ML Model Code Review Checklist

Specialized checklist for reviewing machine learning model code (training, architecture, hyperparameters, evaluation).

---

Model Architecture & Design

Architecture Decisions

• [ ] Model type justified (tree-based, neural network, linear, etc.)
• [ ] Baseline model implemented and documented
• [ ] Model complexity appropriate for data size
• [ ] Architecture matches problem constraints (latency, interpretability)
• [ ] Model inputs and outputs clearly defined
• [ ] Feature dimensionality documented

Modern Best Practices

• [ ] LightGBM/XGBoost considered for tabular data
• [ ] Tree-based methods used as first baseline
• [ ] Computational efficiency considered early
• [ ] Model selection aligns with benchmark results
• [ ] Hyperparameter search space reasonable

Feature Engineering

• [ ] Feature transformations documented
• [ ] Feature scaling/normalization applied correctly
• [ ] Categorical encoding strategy defined
• [ ] Feature interactions considered where appropriate
• [ ] Feature importance tracked
• [ ] No data leakage in feature creation

---

Data Validation & Quality

Data Checks

• [ ] Training data schema validated
• [ ] Missing values handled explicitly
• [ ] Outliers identified and strategy documented
• [ ] Data types correct and consistent
• [ ] Data distribution checked for anomalies
• [ ] Class imbalance identified and addressed

Train/Test Splitting

• [ ] Split strategy documented (random, time-based, stratified)
• [ ] No data leakage between train and test
• [ ] Time ordering preserved for time series
• [ ] Group/entity leakage prevented
• [ ] Validation set held out from all decisions
• [ ] Test set never used during development

Data Leakage Prevention

• [ ] No future information in features
• [ ] Target encoding uses only training data
• [ ] Normalization statistics from training set only
• [ ] No test data used in feature selection
• [ ] IDs and timestamps handled safely
• [ ] Leakage checklist completed

---

Training Pipeline

Training Process

• [ ] Random seeds set for reproducibility
• [ ] Training loop implemented correctly
• [ ] Early stopping implemented (if applicable)
• [ ] Gradient clipping used (if neural network)
• [ ] Batch size and learning rate justified
• [ ] Training progress logged

Hyperparameter Tuning

• [ ] Hyperparameter search strategy documented (grid, random, Bayesian)
• [ ] Search space defined and justified
• [ ] Cross-validation used for tuning
• [ ] Overfitting risk assessed
• [ ] Compute budget considered
• [ ] Best hyperparameters documented

Regularization

• [ ] Regularization techniques applied (L1/L2, dropout, etc.)
• [ ] Regularization strength tuned
• [ ] Early stopping prevents overfitting
• [ ] Model capacity appropriate for data size

---

Model Evaluation

Metrics & Validation

• [ ] Primary metric chosen and justified
• [ ] Guardrail metrics defined (fairness, calibration, cost)
• [ ] Metrics calculated on held-out test set
• [ ] Baseline performance documented
• [ ] Performance compared to business requirements
• [ ] Metric definitions reproducible

Slice Analysis

• [ ] Performance evaluated across key slices
• [ ] Weak segments identified and documented
• [ ] Fairness across sensitive groups checked
• [ ] Error patterns analyzed qualitatively
• [ ] Systematic failures documented

Robustness Checks

• [ ] Model tested on edge cases
• [ ] Adversarial examples considered (if applicable)
• [ ] Sensitivity to input perturbations checked
• [ ] Out-of-distribution behavior documented
• [ ] Model calibration assessed

---

Reproducibility & Versioning

Code & Environment

• [ ] Code version controlled (git commit tracked)
• [ ] Python/package versions pinned
• [ ] Random seeds documented
• [ ] Training can be re-run identically
• [ ] Environment setup documented (requirements.txt, Dockerfile)

Data & Model Versioning

• [ ] Training data version tracked
• [ ] Data snapshot ID recorded
• [ ] Model artifacts versioned
• [ ] Feature set version documented
• [ ] Model registry entry created

Experiment Tracking

• [ ] Experiments logged in tracker (MLflow, W&B)
• [ ] Hyperparameters logged
• [ ] Metrics logged
• [ ] Artifacts stored (model, plots, reports)
• [ ] Run comparisons possible

---

MLOps Integration

Feature Store Integration

• [ ] Features retrieved from feature store
• [ ] Feature versions tracked
• [ ] Train-serve consistency ensured
• [ ] Feature transformations centralized
• [ ] Feature monitoring enabled

CI/CD Integration

• [ ] Model training pipeline automated
• [ ] Unit tests for data processing
• [ ] Model validation checks automated
• [ ] Model promotion workflow defined
• [ ] Environment-specific configs (dev/staging/prod)

Monitoring Setup

• [ ] Data drift detection configured
• [ ] Model performance monitoring planned
• [ ] Retraining triggers defined
• [ ] Alerting thresholds set
• [ ] Fallback strategy documented

---

Clean Code (Core)

• Clean code standard (cite CC-* IDs): ../../../software-clean-code-standard/references/clean-code-standard.md
• Standards: cite CC-* IDs; do not restate rules.
• Common CC-* IDs for model code: CC-NAM-01, CC-FUN-01, CC-FUN-05, CC-TYP-01, CC-TYP-04, CC-ERR-01, CC-SEC-05, CC-DOC-01, CC-DOC-04, CC-TST-01, CC-TST-02, CC-TST-04

Testing

• [ ] Unit tests for data processing functions
• [ ] Unit tests for feature engineering
• [ ] Integration tests for training pipeline
• [ ] Model output validation tests
• [ ] Edge case tests included

Documentation

• [ ] Model architecture documented
• [ ] Training procedure documented
• [ ] Hyperparameter choices explained
• [ ] Evaluation approach documented
• [ ] Known limitations listed
• [ ] Model card created (or planned)

---

Security & Ethics

Data Privacy

• [ ] PII handling compliant with regulations
• [ ] Sensitive features identified
• [ ] Data anonymization applied where needed
• [ ] Access controls on training data
• [ ] No secrets in code or logs

Fairness & Bias

• [ ] Protected attributes identified
• [ ] Fairness metrics computed
• [ ] Bias mitigation strategies considered
• [ ] Disparate impact assessed
• [ ] Ethical considerations documented

Model Safety

• [ ] Failure modes identified
• [ ] Safety checks in prediction pipeline
• [ ] Human-in-the-loop for high-risk decisions
• [ ] Model limitations communicated to stakeholders

---

Performance & Efficiency

Computational Efficiency

• [ ] Training time reasonable for iteration cycle
• [ ] Memory usage within constraints
• [ ] GPU utilization optimized (if applicable)
• [ ] Batch processing used where possible
• [ ] Unnecessary computations eliminated

Inference Performance

• [ ] Inference latency measured
• [ ] Inference meets production requirements
• [ ] Model size acceptable for deployment
• [ ] Quantization or compression considered
• [ ] Batch inference optimized

---

Documentation & Handover

Model Documentation

• [ ] Model evaluation report written
• [ ] Model card created
• [ ] Training notebook/script documented
• [ ] Hyperparameters and architecture documented
• [ ] Performance summary clear

Production Readiness

• [ ] Deployment requirements documented
• [ ] Input/output contracts defined
• [ ] Expected latency and throughput documented
• [ ] Monitoring and alerting plan defined
• [ ] Rollback strategy documented
• [ ] Owners and contacts listed

---

Final Checklist

Before approving ML model code:

• [ ] Model performance meets requirements
• [ ] No data leakage detected
• [ ] Reproducibility verified
• [ ] Tests passing
• [ ] Documentation complete
• [ ] MLOps integration ready
• [ ] Production deployment plan reviewed

Infrastructure as Code Review Checklist

Use this template when reviewing Terraform/Kubernetes/Docker/CI/CD/cloud infrastructure changes.

Core

Standards

• Clean code standard (cite CC-* IDs when applicable): ../../../software-clean-code-standard/references/clean-code-standard.md
• Shared secure code review checklist (baseline): ../../../software-clean-code-standard/assets/checklists/secure-code-review-checklist.md

Intent & Scope

• [ ] PR description states what/why/scope; blast radius and rollback plan are present.
• [ ] Diff matches intent; unrelated refactors are split or explicitly justified.

Change Safety

• [ ] Apply order, rollout strategy, and rollback are clear (especially for breaking or stateful changes).
• [ ] State/data migrations are safe (forward-only vs reversible is explicit).
• [ ] Drift and reconciliation behavior is understood (controllers, desired vs actual state).

Security & Identity

• [ ] Least privilege applied to IAM/RBAC; privileged access is explicit and audited.
• [ ] No hardcoded credentials/secrets; secrets are stored and rotated safely (cite CC-SEC-03).
• [ ] Dependencies are pinned/locked (providers, modules, actions, images) and vetted (cite CC-SEC-05).
• [ ] Network exposure is minimal; public access is explicit, justified, and monitored.

Terraform / IaC

• [ ] Terraform and provider versions are locked; inputs/outputs are typed and documented.
• [ ] Remote state uses locking and encryption; secrets are not stored in state.
• [ ] Resource naming/tagging/labels support ownership, cost, and operations.

Kubernetes

• [ ] Resource requests/limits, liveness/readiness probes, and disruption budgets are set for production workloads.
• [ ] Security context is safe by default (non-root, read-only FS where feasible); network policies restrict traffic.
• [ ] Secrets/config are managed correctly (Secrets for sensitive values; ConfigMaps for non-sensitive).
• [ ] Images are pinned and come from trusted registries; upgrade strategy is clear.

Containers

• [ ] Base images are pinned and minimal; container runs as non-root; no secrets in layers.
• [ ] Health checks exist where the platform supports them; resource usage is bounded.

CI/CD

• [ ] Branch protection and required checks exist for deploy paths (https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches).
• [ ] CI permissions are least-privilege; secrets are masked and never printed.
• [ ] Artifact integrity is addressed for production releases (signing/provenance expectations) [Inference].

Observability

• [ ] Critical systems are observable (logs/metrics/traces appropriate to risk) (cite CC-OBS-03).
• [ ] Alerts have runbooks; alert fatigue is considered (signal > noise).

Optional: AI / Automation

• [ ] IaC validation and policy checks run (fmt/validate, linters, IaC security scanning).
• [ ] Container and dependency scanning is enabled (image vuln scan, secret scan, SBOM as applicable).
• [ ] Automation findings are mapped to CC-* IDs where possible to reduce review noise.

Mobile App Code Review Checklist

Use this template when reviewing iOS/Android/React Native changes.

Core

Standards

• Clean code standard (cite CC-* IDs): ../../../software-clean-code-standard/references/clean-code-standard.md
• Shared mobile release readiness checklist (pre-release gates): ../../../software-clean-code-standard/assets/checklists/mobile-release-checklist.md
• Shared secure code review checklist (baseline): ../../../software-clean-code-standard/assets/checklists/secure-code-review-checklist.md

Intent & Scope

• [ ] PR description states what/why/scope; risk and rollback plan are present.
• [ ] Diff matches intent; unrelated refactors are split or explicitly justified.

Platform Correctness

• [ ] Lifecycle and state management align with platform patterns; state restores correctly after background/kill/rotation.
• [ ] UI thread is not blocked; expensive work is moved off main thread with explicit cancellation where supported.
• [ ] Memory/leak risks assessed (listeners, observers, subscriptions, image caching).
• [ ] Permissions, deep links, push notifications, and background work behave correctly (as applicable).

UX & Accessibility

• [ ] Touch targets, dynamic type/font scaling, and screen reader support are validated for changed flows.
• [ ] Loading/empty/error states are correct and recoverable.

Security & Privacy

• [ ] Secrets are not hardcoded or logged (cite CC-SEC-03, CC-OBS-02).
• [ ] Auth/session tokens follow policy (CSPRNG + expiry/rotation) (cite CC-SEC-07).
• [ ] Sensitive data is stored using platform secure storage (Keychain/Keystore); errors do not leak sensitive context (cite CC-ERR-02).

Reliability & Performance

• [ ] Work is bounded for untrusted/large inputs (cite CC-PERF-01).
• [ ] Obvious hazards avoided (e.g., unbounded list rendering, repeated network calls) (cite CC-PERF-02).
• [ ] Network and I/O have explicit timeouts and retry bounds where supported (cite CC-ERR-03, CC-ERR-04).
• [ ] Offline/poor-network behavior is acceptable for the product (cache, retry UI, backoff).

Observability

• [ ] Crash reporting and telemetry exist for critical user flows (cite CC-OBS-03).
• [ ] Logs are structured where applicable and include correlation identifiers; no sensitive data (cite CC-OBS-01, CC-OBS-02).

Tests

• [ ] New behavior is covered; bug fixes include regression tests (cite CC-TST-01).
• [ ] Tests are deterministic (no time/network flake) (cite CC-TST-02).
• [ ] Critical flows have UI/integration coverage where risk warrants (cite CC-TST-04).

Optional: AI / Automation

• [ ] Static analysis and CI checks are green; automation findings mapped to CC-* IDs where possible.
• [ ] If shipping AI features: privacy boundaries, safe fallbacks, and user-visible recovery are explicit [Inference].

Frontend Code Review Checklist

Use this template when reviewing frontend PRs (React/Next.js/Vue/Angular/TypeScript/JavaScript).

Core

Standards

• Clean code standard (cite CC-* IDs): ../../../software-clean-code-standard/references/clean-code-standard.md
• Shared performance + accessibility checklist: ../../../software-clean-code-standard/assets/checklists/frontend-performance-a11y-checklist.md
• Shared UX design review checklist (optional): ../../../software-clean-code-standard/assets/checklists/ux-design-review-checklist.md

Intent & Scope

• [ ] PR description states what/why/scope; include screenshots/video for UI changes.
• [ ] Diff matches intent; unrelated refactors are split or explicitly justified.

UX Correctness

• [ ] Visual output matches design system/tokens; responsive across breakpoints.
• [ ] Loading/empty/error states are correct and non-jarring.
• [ ] Primary flows remain intuitive; navigation and state changes avoid surprises.

Accessibility

• [ ] Semantic HTML used; headings/landmarks are logical; forms have labels and accessible errors.
• [ ] Keyboard navigation and focus management work for all interactive flows.
• [ ] Touch targets meet WCAG 2.2 SC 2.5.8 target size (24x24 CSS px; exceptions apply) https://www.w3.org/TR/WCAG22/#target-size-minimum

Performance

• [ ] Untrusted or large inputs are bounded (pagination/virtualization/limits) (cite CC-PERF-01).
• [ ] Obvious performance hazards avoided (e.g., N+1 fetching, O(n²) rendering patterns) (cite CC-PERF-02).
• [ ] Rendering avoids unnecessary expensive work on input; code splitting used where appropriate.

Security & Privacy

• [ ] Untrusted content is escaped/sanitized; no unsafe interpolation into HTML (cite CC-SEC-08).
• [ ] Secrets and sensitive data are not shipped to clients or logged (cite CC-SEC-03, CC-OBS-02).
• [ ] Auth/session handling follows product policy (cookie vs storage) and CSRF is handled when needed.

Reliability & Operability

• [ ] Error boundaries or equivalent fault isolation exists for risky UI paths.
• [ ] Async flows have explicit timeout/cancellation where supported; failures are actionable (cite CC-ERR-01, CC-ERR-04).
• [ ] Critical UX paths emit usable telemetry (logs/metrics/traces as applicable) (cite CC-OBS-03).

Tests

• [ ] New behavior has tests; bug fixes include regression tests (cite CC-TST-01).
• [ ] Tests match risk (unit/integration/e2e) rather than blanket thresholds (cite CC-TST-04).

Optional: AI / Automation

• [ ] Lint/typecheck/tests are green; automation findings are mapped to CC-* IDs where possible.
• [ ] Core Web Vitals and bundle-size regressions checked (https://web.dev/vitals/).
• [ ] If shipping AI UX: cancel/stop, streaming state, safe fallbacks, and privacy boundaries are explicit [Inference].

Code Review Automation Tools & Setup

Modern code review combines automated checks with manual review for maximum effectiveness. Automation finds 60-70% of issues, letting human reviewers focus on architecture, logic, and business concerns.

Automation Strategy

Three-Layer Approach

Layer 1: Pre-commit checks (Local)

• Runs on developer machine before commit
• Fast feedback (seconds)
• Catches obvious issues early

Layer 2: PR checks (CI/CD)

• Runs on every pull request
• Comprehensive analysis (minutes)
• Blocks merge if critical issues found

Layer 3: Continuous monitoring (Production)

• Runs on deployed code
• Security scanning, dependency updates
• Weekly reports

Essential Tools by Category

1. Code Linters

JavaScript/TypeScript:

// .eslintrc.json
{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-strict/recommended",
    "plugin:security/recommended"
  ],
  "plugins": ["security", "sonarjs"],
  "rules": {
    "complexity": ["error", 10],
    "max-depth": ["error", 3],
    "max-lines-per-function": ["error", 50],
    "sonarjs/cognitive-complexity": ["error", 15]
  }
}

Python:

# pyproject.toml
[tool.ruff]
line-length = 100
select = ["E", "F", "I", "N", "W", "B", "C90"]
ignore = ["E501"]

[tool.ruff.mccabe]
max-complexity = 10

Go:

# .golangci.yml
linters:
  enable:
    - gofmt
    - govet
    - staticcheck
    - gosec
    - errcheck
    - ineffassign

2. Code Formatters

JavaScript/TypeScript - Prettier:

// .prettierrc
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2
}

Python - Black:

[tool.black]
line-length = 100
target-version = ['py311']

Go - gofmt (built-in):

gofmt -w .

3. Static Analysis

SonarQube/SonarCloud (Multi-language):

# sonar-project.properties
sonar.projectKey=my-project
sonar.sources=src
sonar.tests=tests
sonar.coverage.exclusions=**/*test*/**
sonar.javascript.lcov.reportPaths=coverage/lcov.info

# Quality gates
sonar.qualitygate.wait=true
sonar.qualitygate.timeout=300

CodeClimate (Multi-language):

# .codeclimate.yml
version: "2"
checks:
  argument-count:
    enabled: true
    config:
      threshold: 4
  complex-logic:
    enabled: true
    config:
      threshold: 4
  file-lines:
    enabled: true
    config:
      threshold: 250
  method-complexity:
    enabled: true
    config:
      threshold: 5
  method-lines:
    enabled: true
    config:
      threshold: 25

ESLint Plugin Security (JavaScript):

npm install --save-dev eslint-plugin-security

4. Security Scanners

Snyk (Dependency vulnerabilities):

# .github/workflows/security.yml
name: Security Scan
on: [pull_request]
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: snyk/actions/node@master
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
        with:
          args: --severity-threshold=high

Trivy (Container security):

trivy image --severity HIGH,CRITICAL myimage:latest

Semgrep (Code patterns):

# .semgrep.yml
rules:
  - id: hardcoded-secret
    patterns:
      - pattern: password = "..."
    message: Hardcoded password detected
    severity: ERROR

5. Test Coverage Tools

JavaScript - Istanbul/NYC:

// package.json
{
  "scripts": {
    "test": "jest --coverage",
    "test:coverage": "jest --coverage --coverageThreshold='{\"global\":{\"branches\":80,\"functions\":80,\"lines\":80}}'"
  }
}

Python - Coverage.py:

[tool.coverage.run]
source = ["src"]
omit = ["*/tests/*", "*/test_*.py"]

[tool.coverage.report]
fail_under = 80
show_missing = true

Go - Built-in:

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

6. AI-Powered Review Tools ()

GitHub Copilot for Pull Requests:

• Generates PR summaries
• Suggests reviewers
• Identifies potential issues
• Free for GitHub Enterprise

Qodo (formerly Codium):

# .qodo.yml
features:
  pr_reviewer: true
  auto_improve: true
  test_generation: true

pr_reviewer:
  auto_review: true
  inline_suggestions: true
  security_check: true

CodeRabbit:

• AI code reviews
• Learning from team patterns
• Context-aware suggestions

Amazon CodeGuru:

# buildspec.yml
phases:
  pre_build:
    commands:
      - aws codeguru-reviewer associate-repository
      - aws codeguru-reviewer create-code-review

7. Dependency Management

Dependabot (GitHub):

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
    reviewers:
      - "team-leads"
    labels:
      - "dependencies"

Renovate (Multi-platform):

{
  "extends": ["config:base"],
  "rangeStrategy": "bump",
  "packageRules": [
    {
      "updateTypes": ["minor", "patch"],
      "automerge": true
    }
  ]
}

8. Stack-Aware Merge Queues (2026)

Stacked PRs break large changes into sequential, dependent pull requests. Stack-aware merge queues treat these stacks as first-class citizens, validating entire stacks atomically rather than testing each PR independently.

Graphite:

# Install CLI
npm install -g @withgraphite/graphite-cli

# Create stacked PRs
gt stack submit

# Queue entire stack for merge
gt stack merge

• Treats PR stacks as first-class citizens
• Runs CI on entire stack atomically (top PR contains all changes)
• 74% reduction in median merge time (Ramp Engineering)
• Eliminates CI redundancy across stack
• graphite.com

Aviator:

# aviator.yaml
merge_rules:
  - name: default
    conditions:
      - base_branch: main
    merge_mode:
      type: parallel
      parallel_mode:
        max_parallel_builds: 5
    enable_stacked_prs: true

• Stack-aware queue with partial stack support
• Speculative execution with intelligent bisection
• aviator.co

Meta Sapling:

# Sapling SCM with built-in stacking
sl stack  # View current stack
sl submit # Submit stack for review

• Source control system with native stacking support
• sapling-scm.com

Measured Benefits:

When to Use:

• Large features requiring multiple dependent changes
• Teams with >10 engineers experiencing merge conflicts
• High-velocity teams with frequent deployments
• When review bottlenecks slow delivery

CI/CD Pipeline Configuration

GitHub Actions Example

# .github/workflows/pr-checks.yml
name: PR Checks

on:
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint

  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run format:check

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm test -- --coverage
      - name: Coverage check
        run: |
          if [ $(cat coverage/coverage-summary.json | jq '.total.lines.pct') -lt 80 ]; then
            echo "Coverage below 80%"
            exit 1
          fi

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: snyk/actions/node@master
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
      - run: npm audit --audit-level=high

  static-analysis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sonarsource/sonarcloud-github-action@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: qodo-ai/pr-agent@main
        env:
          QODO_API_KEY: ${{ secrets.QODO_API_KEY }}

GitLab CI Example

# .gitlab-ci.yml
stages:
  - lint
  - test
  - security
  - quality

lint:
  stage: lint
  script:
    - npm ci
    - npm run lint

test:
  stage: test
  script:
    - npm ci
    - npm test -- --coverage
  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

security:
  stage: security
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker run --rm -v $(pwd):/src aquasec/trivy fs /src

code_quality:
  stage: quality
  image: sonarsource/sonar-scanner-cli:latest
  script:
    - sonar-scanner

Pre-commit Hooks

Husky + lint-staged (JavaScript):

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "lint-staged": {
    "*.{js,ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "jest --bail --findRelatedTests"
    ],
    "*.{json,md}": ["prettier --write"]
  }
}

pre-commit (Python):

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black

  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: v0.1.9
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]

  - repo: https://github.com/PyCQA/bandit
    rev: 1.7.6
    hooks:
      - id: bandit
        args: ['-c', 'pyproject.toml']

Tool Selection Matrix

Configuration Best Practices

1. Fail Fast, Fail Clear

# Good - Clear failure message
- name: Check coverage
  run: |
    COVERAGE=$(cat coverage/coverage-summary.json | jq '.total.lines.pct')
    if (( $(echo "$COVERAGE < 80" | bc -l) )); then
      echo "[FAIL] Coverage is $COVERAGE%, minimum is 80%"
      echo "Run 'npm test -- --coverage' locally to see gaps"
      exit 1
    fi

2. Cache Dependencies

# GitHub Actions
- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

3. Parallel Execution

# Run independent checks in parallel
jobs:
  lint:
    # ...
  test:
    # ...
  security:
    # ...
# These all run simultaneously

4. Progressive Enhancement

Phase 1: Basic checks (week 1)

• Linter
• Formatter
• Basic tests

Phase 2: Quality gates (week 2-3)

• Coverage requirements
• Security scanning
• Static analysis

Phase 3: Advanced automation (month 2+)

• AI-powered review
• Automated dependency updates
• Performance regression testing

Metrics Dashboard

What to Track

# Example metrics.yml
code_quality:
  coverage_threshold: 80
  max_complexity: 10
  max_function_length: 50
  max_file_length: 300

security:
  max_high_vulnerabilities: 0
  max_medium_vulnerabilities: 5
  dependency_update_lag_days: 14

review_process:
  max_review_time_hours: 24
  max_pr_size_lines: 400
  required_approvals: 2

performance:
  build_time_minutes: 5
  test_time_minutes: 3
  deploy_time_minutes: 10

Visualization Tools

SonarQube Dashboard:

• Technical debt ratio
• Code smells
• Security hotspots
• Coverage trends

CodeClimate Dashboard:

• Maintainability grade
• Test coverage
• Code duplication
• Complexity trends

Custom Grafana Dashboard:

-- PR metrics
SELECT
  DATE(created_at) as date,
  AVG(time_to_first_review) as avg_review_time,
  AVG(lines_changed) as avg_pr_size,
  COUNT(*) as total_prs
FROM pull_requests
WHERE created_at > NOW() - INTERVAL '30 days'
GROUP BY DATE(created_at)

Cost Considerations

Open Source (Free)

• ESLint, Prettier, Black
• GitHub Actions (2000 min/month)
• Dependabot
• SonarCloud (public repos)

Small Team ($50-200/month)

• GitHub Team ($4/user)
• Snyk ($25/month)
• CodeClimate ($249/month for small team)

Enterprise ($500+/month)

• SonarQube Enterprise
• Snyk Enterprise
• CodeRabbit Teams
• GitHub Enterprise

Troubleshooting

Common Issues

False Positives:

// Suppress specific rules when necessary
/* eslint-disable-next-line security/detect-object-injection */
const value = obj[dynamicKey];

Slow CI:

# Cache everything possible
- uses: actions/cache@v3
  with:
    path: |
      ~/.npm
      ~/.cache
      node_modules

Flaky Tests:

// Retry flaky tests automatically
jest.retryTimes(3, { logErrorsBeforeRetry: true });

Resources

• GitHub Actions: https://docs.github.com/actions
• SonarQube: https://docs.sonarqube.org/
• Snyk: https://docs.snyk.io/
• ESLint: https://eslint.org/docs/
• Semgrep: https://semgrep.dev/docs/

Code Review Metrics

Measuring code review effectiveness without creating perverse incentives. This guide covers what to measure, how to interpret metrics, and how to build dashboards that drive improvement rather than gaming.

---

Table of Contents

1. Why Measure Code Review 2. Review Turnaround Time 3. Review Thoroughness 4. Defect Escape Rate 5. Review Cycle Time and Iterations 6. Reviewer Load Balancing 7. DORA Metrics Intersection 8. Avoiding Gaming and Perverse Incentives 9. Dashboard Design 10. Implementation Guide 11. Anti-Patterns

---

Why Measure Code Review

Goals of Review Metrics

What Metrics Cannot Tell You

Metrics measure process efficiency, not review quality. A fast, low-iteration review could mean:

• The code was well-written and easy to review (good)
• The reviewer rubber-stamped it (bad)

Always interpret metrics in context. Use them as diagnostic signals, not performance targets.

---

Review Turnaround Time

Key Metrics

Measurement

-- Time to first response (PostgreSQL example)
SELECT
  pr.id,
  pr.created_at,
  MIN(comment.created_at) AS first_response_at,
  EXTRACT(EPOCH FROM (
    MIN(comment.created_at) - pr.created_at
  )) / 3600 AS hours_to_first_response
FROM pull_requests pr
LEFT JOIN review_comments comment
  ON comment.pr_id = pr.id
  AND comment.author_id != pr.author_id
WHERE pr.created_at > NOW() - INTERVAL '30 days'
GROUP BY pr.id, pr.created_at;

SLA by Priority

Turnaround Distribution

Track the distribution, not just the average:

TTFR Distribution (last 30 days):
  < 1 hour:    25%  -- Excellent
  1-4 hours:   40%  -- Good
  4-8 hours:   20%  -- Acceptable
  8-24 hours:  10%  -- Needs attention
  > 24 hours:   5%  -- Problem

The P90 and P95 values matter more than the median. A median of 3 hours is fine, but a P95 of 48 hours indicates a systemic problem for some PRs.

---

Review Thoroughness

Defects Found in Review

Categorizing Review Comments

Establish a tagging system for review comments to track what reviewers catch:

Review Comment Quality Ratio

Quality ratio = (security + bug + perf + design comments) / total comments

Target: > 0.5 (at least half of comments are substantive)
Warning: < 0.3 (most comments are nits)

Meaningful vs Superficial Reviews

Track the proportion of reviews with zero substantive comments:

Reviews with 0 substantive comments: 30% -- May indicate rubber-stamping
Reviews with 1-3 substantive comments: 50% -- Normal range
Reviews with 4+ substantive comments: 20% -- Complex PRs or thorough review

A high percentage of zero-comment reviews combined with post-merge defects suggests review thoroughness is low.

---

Defect Escape Rate

Definition

Defect escape rate measures bugs that pass through code review and reach production (or are found in QA/staging).

Escape Rate = Defects found after merge /
              (Defects found in review + Defects found after merge)

Target: < 20% (80%+ of defects caught in review)
Warning: > 40% (review process needs significant improvement)

Tracking Post-Merge Defects

Escape Rate by Category

Category         Found in Review    Escaped    Escape Rate
Security         12                 2          14%
Correctness      45                 18         29%
Performance      8                  5          38%
Integration      3                  7          70%

Insight: Integration issues frequently escape review because
they require running the full system, not just reading diffs.

Using Escape Rate to Improve

When a defect escapes:

1. Retroactive review: Could this have been caught in the original PR? 2. Root cause: Was it a reviewer oversight, missing test, or insufficient context? 3. Process improvement: Does the checklist need a new item? Do we need more test coverage? 4. Knowledge sharing: Should the team discuss this pattern?

---

Review Cycle Time and Iterations

Key Metrics

Iteration Analysis

PR Iteration Breakdown (last 30 days):
  1 round (approve on first review):    45%
  2 rounds:                             35%
  3 rounds:                             15%
  4+ rounds:                             5%  -- Investigate these

What High Iteration Counts Indicate

---

Reviewer Load Balancing

Load Metrics

Detecting Imbalances

-- Review distribution across team members (last 30 days)
SELECT
  reviewer.name,
  COUNT(DISTINCT pr.id) AS reviews_completed,
  AVG(EXTRACT(EPOCH FROM (
    review.submitted_at - pr.review_requested_at
  )) / 3600) AS avg_hours_to_review
FROM reviews review
JOIN pull_requests pr ON review.pr_id = pr.id
JOIN users reviewer ON review.reviewer_id = reviewer.id
WHERE review.submitted_at > NOW() - INTERVAL '30 days'
GROUP BY reviewer.name
ORDER BY reviews_completed DESC;

Healthy Distribution Indicators

Team of 8 engineers, 40 PRs/week:

Healthy:
  Alice:   6 reviews  (15%)
  Bob:     5 reviews  (12.5%)
  Carol:   5 reviews  (12.5%)
  Dave:    5 reviews  (12.5%)
  Eve:     5 reviews  (12.5%)
  Frank:   5 reviews  (12.5%)
  Grace:   5 reviews  (12.5%)
  Hank:    4 reviews  (10%)

Unhealthy:
  Alice:  15 reviews  (37.5%)  -- Bottleneck
  Bob:     8 reviews  (20%)
  Carol:   7 reviews  (17.5%)
  Dave:    5 reviews  (12.5%)
  Eve:     3 reviews  (7.5%)
  Frank:   1 review   (2.5%)
  Grace:   1 review   (2.5%)
  Hank:    0 reviews  (0%)     -- Not reviewing at all

---

DORA Metrics Intersection

How Review Practices Affect DORA

Correlating Review Metrics with DORA

Track monthly:
  Review turnaround (P50, P90) vs Lead Time for Changes
  Defect escape rate vs Change Failure Rate
  P0 review SLA compliance vs Mean Time to Recovery
  PR throughput vs Deployment Frequency

The Review Bottleneck Signal

If lead time is high but coding time is low, review is likely the bottleneck:

Total Lead Time: 5 days
  - Coding time:     1 day   (20%)
  - Review wait:     3 days  (60%)  <-- Bottleneck
  - CI + merge:      0.5 day (10%)
  - Deploy wait:     0.5 day (10%)

Focus improvement efforts on review turnaround when this pattern appears.

---

Avoiding Gaming and Perverse Incentives

Common Gaming Patterns

Principles for Healthy Metrics

1. Measure for diagnosis, not performance evaluation. Review metrics should inform process improvement, not individual performance reviews.

2. Use composite indicators, not single metrics. Fast reviews are only good if the defect escape rate is also low. Track both together.

3. Track trends, not absolutes. A team with 6-hour TTFR improving to 4-hour is healthier than a team at 2-hour TTFR that is rubber-stamping.

4. Make metrics visible but not punitive. Display team dashboards. Do not rank individuals or tie metrics to bonuses.

5. Periodically audit the metrics. Spot-check that low TTFR corresponds to substantive first comments. Verify that low escape rate is not hiding unfiled bugs.

Suggested Composite Health Score

Review Health Score = weighted average of:
  - TTFR P90 < SLA:           30% weight
  - Defect escape rate < 20%: 30% weight
  - Review rounds <= 2 avg:   20% weight
  - Load balance Gini < 0.3:  10% weight
  - Abandonment rate < 5%:    10% weight

Score interpretation:
  0.8-1.0: Excellent review process
  0.6-0.8: Good, minor improvements possible
  0.4-0.6: Needs attention in specific areas
  < 0.4:   Significant process issues

---

Dashboard Design

Team-Level Dashboard

+--------------------------------------------------+
|  CODE REVIEW HEALTH - January 2026               |
+--------------------------------------------------+
|                                                    |
|  TURNAROUND              QUALITY                  |
|  TTFR (P50): 2.3h       Escape Rate: 18%         |
|  TTFR (P90): 7.1h       Comments/PR: 3.2 avg     |
|  TTA  (P50): 18.4h      Quality ratio: 0.62      |
|                                                    |
|  THROUGHPUT              BALANCE                   |
|  PRs merged: 142/mo     Gini coeff: 0.24          |
|  Avg rounds: 1.8        Max queue: 4 PRs          |
|  Abandon rate: 3.2%     Overloaded: 0 people      |
|                                                    |
|  TRENDS (12 weeks)                                |
|  TTFR:    Improving                                |
|  Escapes: Improving                                |
|  Load:    Stabilized                               |
+--------------------------------------------------+

Key Dashboard Components

Data Sources

---

Implementation Guide

Phase 1: Baseline (Week 1-2)

1. Start collecting TTFR and TTA from your Git platform API 2. Calculate current review distribution across team 3. Establish current defect escape rate (review last month's bugs) 4. Set initial targets based on baseline (improve by 20%)

Phase 2: Visibility (Week 3-4)

1. Build a simple dashboard (Grafana, Datadog, or spreadsheet) 2. Share with team in sprint retrospective 3. Discuss the numbers without assigning blame 4. Identify one area to improve

Phase 3: Process Improvement (Month 2)

1. Implement changes based on metrics (reviewer rotation, PR size limits) 2. Track metrics weekly 3. Adjust targets as the team improves 4. Add review SLAs to team agreements

Phase 4: Continuous Monitoring (Ongoing)

1. Automate data collection (scheduled scripts or engineering platform) 2. Set up alerts for anomalies (TTFR P90 > 24 hours, escape rate spike) 3. Monthly review of composite health score 4. Quarterly target adjustment

GitHub Actions Metric Collection

# .github/workflows/review-metrics.yml
name: Review Metrics
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM
  workflow_dispatch:

jobs:
  collect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Collect PR metrics
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api graphql -f query='
            query {
              repository(owner: "org", name: "repo") {
                pullRequests(last: 50, states: MERGED) {
                  nodes {
                    createdAt
                    mergedAt
                    reviews(first: 10) {
                      nodes {
                        createdAt
                        state
                        author { login }
                      }
                    }
                    comments { totalCount }
                    additions
                    deletions
                  }
                }
              }
            }
          ' > metrics.json

---

Anti-Patterns

1. Metrics Without Context

Problem: Presenting raw numbers without explaining what they mean or what is actionable.

Fix: Always pair metrics with interpretation and recommended actions.

2. Individual Leaderboards

Problem: Ranking reviewers by speed or volume, creating competition instead of collaboration.

Fix: Show team-level metrics only. Use individual data privately for coaching, not public ranking.

3. Optimizing One Metric at the Expense of Others

Problem: Pushing TTFR down to 30 minutes but defect escape rate doubles because reviews are superficial.

Fix: Use composite health scores. Improvements must not degrade other metrics.

4. Measuring What Is Easy, Not What Matters

Problem: Tracking comments per PR (easy to count) but ignoring whether those comments catch real bugs.

Fix: Invest in categorizing review comments and tracking escape rate, even though they require more effort.

5. Setting Targets Too Aggressively

Problem: Setting 1-hour TTFR as a target when the team averages 8 hours, causing stress and gaming.

Fix: Set targets at 20% improvement from baseline. Ratchet down gradually over quarters.

---

Cross-References

• operational-playbook.md -- SLA definitions and priority matrix
• large-pr-review-strategies.md -- PR size impact on review effectiveness
• automation-tools.md -- Tools for automating metric collection
• psychological-safety-guide.md -- Presenting metrics without blame
• ../../software-clean-code-standard/references/clean-code-standard.md -- Quality standards that reviews enforce

.NET/EF Core Crypto Integration Review Rules

Review rules for C#/.NET crypto/fintech services using Entity Framework Core. Practical, minimal rules focused on correctness, security, readability, and maintainability.

---

0. Review Scope Rule

• Review only new or modified code in the merge request, not the entire repository
• Feedback must be limited to changes in the diff unless new code directly interacts with existing components where consistency is important
• Do not comment on untouched legacy code

---

1. Correctness

• All conditional branches are handled — no missing scenarios
• Input parameters are validated at a basic level (null/empty, format, ranges)
• Methods do not return null when a proper result or explicit failure is expected
• No silent-fail paths — deviations lead to explicit outcomes
• No unreachable or dead code
• Calculations use decimal for financial values, with proper comparisons and rounding
• All dates and times use UTC
• Status transitions are valid and do not skip intermediate states
• DTO → model → database mappings are consistent and do not lose data
• Edge cases are handled: empty collections, missing data, zero values

---

2. Security

• No secrets in code: API keys, tokens, connection strings must come from configuration or environment variables
• Logs must not contain sensitive data: tokens, passwords, private keys
• External inputs are validated at a basic level before use
• SQL queries are not constructed manually — ORM or parameterized queries must be used
• Error messages do not expose internal technical details (stack traces, configuration values)

---

3. Error Handling

• Errors are handled explicitly — no silent failures
• Exceptions are not swallowed; if caught, they must be logged
• No unhandled exceptions leaking into higher layers
• External errors (DB, HTTP, API) are minimally handled: return a failure or meaningful result
• Error messages are clear but do not reveal sensitive or internal details
• Methods returning Result or Result<T> follow a consistent Success/Fail pattern

---

4. Async / I/O

• Async methods are used for I/O operations
• No blocking calls (.Result, .Wait())
• No missing await inside async methods
• CancellationToken is passed when supported
• No heavy CPU work inside async methods unless intentional
• No unintended fire-and-forget calls

---

5. Database (EF Core)

• Database queries are simple and predictable — no dynamic SQL
• No queries inside loops leading to repeated DB calls (N+1 patterns)
• Only necessary data is loaded — avoid overusing .Include
• Use AsNoTracking for read-only scenarios
• LINQ queries remain readable and not overly complex
• Absence of data is handled explicitly — no silent null returns

---

6. External API

• External API calls are encapsulated in dedicated clients or services
• API responses are checked for success
• API errors result in clear failure handling
• No empty catch blocks
• Response data is validated before use (null checks, required fields)
• All external calls are async and respect CancellationToken when possible

---

7. Readability & Maintainability

• Names of classes, methods, and variables clearly reflect their purpose
• No dead or commented-out code
• TODO comments are acceptable if brief and relevant
• Methods perform a single, clear responsibility
• Repeated logic is extracted into helpers or shared methods
• Prefer early returns over deep nesting
• Formatting follows project conventions (editorconfig, style rules)

---

8. Unit & API Tests

• Updated logic is covered by at least one type of test: unit tests or API tests
• Minimum coverage: one success scenario
• Tests are readable and not overly complex
• Mocks are used only when necessary; simple logic is tested directly
• Tests do not depend on external services or the network
• Test names reflect expected behavior
• Key input arguments are explicitly asserted — avoid It.IsAny<T>() when specific values matter

---

9. Behavioral Infrastructure Changes

When a change alters runtime semantics (consumer commit behavior, retry/DLQ routing, failure handling, shutdown flow):

• Does this change alter commit, retry, or DLQ semantics? If yes, is the new behavior explicitly opt-in?
• Are legacy extension points (shared subscriptions, custom IMessageSubscription, fan-out consumers) still exercised by tests?
• Is OperationCanceledException kept outside the normal failure path? Cancellation must exit the processing loop before failure routing kicks in
• Are failure-routing failures (e.g., failed DLQ publish) isolated to the affected partition, not killing the whole consumer task?
• For high-risk behavioral work, use the review-first fix loop: implement → review → isolate highest-risk gap → fix only the risky slice → revalidate. This is not cleanup — it is how behavioral infrastructure work becomes safe

---

10. Merge Requests

• MR contains logically related changes — feature, bugfix, or refactor
• If refactoring is included, it is separated from functional changes (structurally or via commits)
• No temporary, debug, or commented-out code
• MR size remains reasonable and easy to review
• All CI checks pass
• Commit messages and branch names reflect the purpose of the change

Implementing Effective Code Reviews Checklist

Operational practices distilled from “Implementing Effective Code Reviews.”

Process Setup

• Define review goals up front (defect discovery vs. knowledge sharing vs. risk sign-off); pick practices accordingly.
• Keep reviews small: target ≤200–250 LOC per review; split larger changes and avoid >2000 LOC.
• Timebox sessions to ~60 minutes; schedule follow-ups instead of marathon reviews.
• Require author pre-checks: self-review, lint/tests run, and annotated diffs explaining intent, risks, and areas needing attention.

Reviewer Playbook

• Read context first: change summary, issue link, risk areas, and test plan.
• Check correctness paths first (happy/error/boundary), then design (responsibilities, coupling), then tests/observability.
• Verify inputs/outputs, data invariants, and error handling; ensure logs/metrics exist on critical paths.
• Demand tests for new behavior and for fixed bugs that fail before the fix.

Author Responsibilities

• Submit focused diffs; avoid mixing refactors with features unless clearly separated and labeled.
• Annotate diffs with rationale, assumptions, risk areas, and data shape examples.
• Respond promptly and concretely to review comments; capture agreed changes in code, not just discussion.

Tooling and Enforcement

• Enforce size/time limits in tooling; flag pass-through reviews (e.g., duration <30s or >1500 LOC/hour) as invalid.
• Require checklist acknowledgment before approval (size, tests run, risk reviewed, logging/metrics added where needed).
• Track review metrics (defect density vs. size, turnaround time, rework rate) to tune practices, not to game counts.

Social and Communication

• Keep feedback specific and behavior-focused; avoid personal language.
• Prioritize safety issues first, then correctness, then design/readability; mark severities to guide fixes.
• Encourage “ask” comments for clarification and “action” comments for required changes; avoid vague requests.

Continuous Improvement

• Run periodic retros on review effectiveness; adjust size limits, checklists, and SLAs based on data.
• Share notable findings and patterns with the team; convert recurring issues into linters or templates.
• Calibrate reviewers: pair-review occasionally to align standards and spread domain knowledge.