review

name	review
description	Multi-pass code review covering Minter spec coverage, code quality, design system compliance, test strategy, and architecture. Use before considering a feature done or creating a PR.

/review

Systematic multi-pass code review. Run this AFTER /consistency-check passes and E2E tests pass.

Phase 0: Gather Context

Before reviewing, understand what changed:

git diff main...HEAD --stat
git diff main...HEAD

Read the CLAUDE.md to refresh on project conventions. If there's a Minter spec for this feature, read it via MCP (list_specs → inspect).

Phase 1: Minter Spec Coverage

Use Minter MCP tools:

• list_specs — find the spec for this feature
• inspect — view behavior count and categories
• assess — check for quality issues (missing error cases, edge cases, smells)
• graph — check dependency impact

Verify:

• Every spec behavior has a corresponding @minter:e2e or @minter:unit tag in tests
• Run minter coverage to check coverage percentage
• Flag any untested behaviors
• Check minter lock is up to date

Phase 2: File-by-File Code Quality

For EACH changed file, check:

Code quality & simplicity:

• Functions under 30 lines (suggest splitting if longer)
• No deep nesting (max 3 levels)
• No magic numbers or strings
• Clear variable names
• No commented-out code

TypeScript strictness:

• No any types — find the proper type
• No type assertions (as X) unless absolutely necessary with a comment explaining why
• No unused variables or imports
• No @ts-ignore or @ts-expect-error without explanation

Security:

• Every Convex mutation/query calls requireAuthenticated() or appropriate auth check FIRST
• All user input validated with Zod before processing
• No hardcoded secrets, tokens, or API keys
• No SQL injection vectors (not applicable with Convex, but check for any raw queries)

Design system compliance:

• All UI components imported from packages/ui/ — no inline component definitions in app code
• No hardcoded colors, spacing, or font sizes — only Panda CSS tokens
• No inline style={{}} attributes (except in the initial landing page scaffold)
• If a component is used more than once, it should be in packages/ui/ with a Storybook story

i18n compliance:

• Zero hardcoded user-facing strings — all text through Paraglide messages
• Code identifiers and comments in English only

Analytics:

• User actions and milestones tracked via PostHog (consent-gated)
• Error events captured

Phase 3: Test Strategy

E2E tests (primary):

• Every user-facing feature has at least one E2E test
• Happy path covered
• Key error states covered
• Tests use real browser interactions (not test IDs when possible)
• Tests run against real /preview backend (never mocked)

Unit tests (secondary):

• Only for pure functions (validators, formatters, calculations)
• No mocks — if mocks are needed, it should be an E2E test
• Clear input → expected output pattern

Seed data:

• New entities added to seed.ts
• Seed data matches what E2E tests expect

Phase 4: CI & Tooling

• pnpm check passes (lint, format, typecheck, unit tests)
• minter ci passes (spec integrity)
• E2E tests structured correctly (correct test project in Playwright config)
• No new dependencies without justification

Phase 5: Big Picture

• Does the architecture make sense for this feature?
• Any over-engineering or premature abstractions?
• Is the UX intuitive? Could it be simpler?
• Performance concerns? (unnecessary re-renders, large bundles, N+1 queries)
• Does this change impact other features? (check minter graph --impacted)

Output Format

Present findings sequentially: F1, F2, F3...

**F1** [Critical] apps/web/app/routes/dashboard.tsx:42
Description of the issue.
Suggestion: How to fix it.

**F2** [High] convex/listings.ts:15
Description of the issue.
Suggestion: How to fix it.

Severities:

• Critical — Must fix before merge. Security issue, broken functionality, data loss risk.
• High — Should fix before merge. Missing tests, design system violation, auth check missing.
• Medium — Consider fixing. Code smell, unclear naming, minor DX issue.
• Low — Nit. Style preference, minor improvement suggestion.
• Info — Observation. Not a problem, just noting for context.