Code Review

Code Review

Owner: Engineering Last reviewed: 2026-Q2

Purpose: Improve quality, spread context, and reduce risk while keeping velocity.

Author Checklist

  • Scope: small, single-purpose PR with clear description
  • Tests: add/adjust unit/integration tests; run locally
  • API: update OpenAPI and regenerate clients if changed
  • Security: validate inputs, authZ boundaries, secret handling
  • Observability: logs/traces around new code paths; health if new dependency
  • Docs: update handbook/ADRs when relevant

Reviewer Guidelines

  • Respectful and specific; focus on correctness, clarity, and impact
  • Prefer suggestions over mandates; link to precedents in repo
  • Look for: data access boundaries, error handling, validation, performance footguns, race conditions
  • Ensure migrations are safe and backward compatible

Risky Changes

  • Require two approvals for changes touching authentication, authorization, billing/entitlements, secrets, infrastructure, migrations, destructive data operations, file upload/security scanning, document permissions, board/action-point sharing, or provider integrations that can incur cost.
  • Require explicit rollback notes for migrations, deploy pipeline changes, and production configuration changes.

What to Look For (Repo-Specific)

  • Backend
    • Routes adhere to schema models in backend/py/schemas/*
    • Use async DB sessions from db/database.py; avoid blocking calls
    • Enforce dual-auth checks where required (Clerk + local user)
    • File uploads respect core/config.py constraints
    • External calls (Azure/OpenAI) are retriable and bounded (timeouts)
  • Frontend
    • Use generated clients (src/api/generated) and thin wrappers (src/api/*)
    • Query/mutation via React Query with proper cache keys and invalidations
    • Accessible components; Tailwind utility classes consistent
    • Error handling via useApiError; no leaking raw server errors to users

Merging

  • Require at least one approving review (two for risky changes)
  • CI must be green; manual validation notes for deployments welcome
  • Squash merge; keep messages meaningful and link issues
WorkflowOnboarding