Code Review

Code Review

Review Posture

Review as a principal engineer responsible for long-term product health. Prioritize correctness, architecture, maintainability, reusability, testing, documentation, observability, operational risk, and delivery safety. Keep style comments secondary unless they hide a real defect or maintenance cost.

For broad or full-app reviews, read references/principal-review-checklist.md after identifying the stack, app boundaries, and user workflows.

Workflow

1. Establish scope:

   • Identify the app type, primary workflows, deployment model, data stores, background jobs, integrations, and test framework.
   • Inspect recent diffs when reviewing a branch or PR; inspect the full flow when reviewing an application area.
   • Note what was not reviewed or could not be verified.

2. Build the mental model:

   • Trace request, UI, job, and data paths end to end.
   • Identify shared abstractions, ownership boundaries, and repeated patterns.
   • Prefer the repository's existing conventions before recommending new structure.

3. Review high-impact concerns first:

   • Correctness and user-visible behavior.
   • Data integrity, migrations, lifecycle cleanup, idempotency, and concurrency.
   • Architecture boundaries, coupling, duplication, and cohesion.
   • Reusability of helpers, services, components, templates, and tests.
   • Error handling, logging, observability, and operational failure modes.
   • Security-adjacent risks when obvious, while leaving deep vulnerability review to a dedicated security review.

4. Check README and docs:

   • Verify setup, environment variables, commands, background jobs, deployment steps, and important workflows match the code.
   • Flag stale, missing, or misleading README content.
   • Recommend exact documentation updates when possible.

5. Check test coverage:

   • Identify the test strategy and what commands should be run.
   • Look for coverage of critical flows, edge cases, failure paths, integrations, migrations, and background jobs.
   • Flag untested behavior when the risk justifies tests.
   • Prefer focused tests that protect behavior over broad, brittle test expansion.

6. Validate findings:

   • Ground each issue in code, config, docs, tests, or observed behavior.
   • Avoid speculative complaints without impact.
   • Run focused tests or static checks when feasible.
   • Distinguish confirmed findings from questions or improvement ideas.

Output Format

Use a code-review stance by default:

• Findings first, ordered by severity.
• Include file and line references for local code when available.
• For each finding, state impact and a concrete fix.
• Then list open questions or assumptions.
• Then summarize what was reviewed and tests/checks run.

If no material issues are found, say so clearly and mention residual risks or missing verification.

Severity

• Critical: likely data loss, major outage, broken core workflow, unsafe deployment behavior, or severe security-impacting defect.
• High: incorrect cross-user behavior, broken billing/auth/notification flows, migration or cleanup risks, major test gap around risky logic, or architectural issue likely to cause recurring defects.
• Medium: maintainability or reuse issue with clear cost, brittle integration, incomplete docs for important operations, missing tests for meaningful edge cases.
• Low: minor cleanup, naming, local readability, non-blocking documentation polish, or optional hardening.

Implementation Follow-Through

When the user asks to fix issues, make scoped changes that fit the existing codebase. Add or adjust tests proportional to risk, update the README when behavior or configuration changes, and run the smallest meaningful verification set before reporting back.

Guardrails

• Do not turn reviews into broad rewrites unless the user asks for implementation.
• Do not report generic best practices without a specific app impact.
• Do not demand abstractions for one-off code; recommend reuse only when it reduces real duplication or coupling.
• Do not overwrite user changes or unrelated work in a dirty tree.
• Do not expose secrets found during review; redact values and identify the location safely.