Code Review Methodology

Run a systematic pre-PR review for template-ts codebases. Identify critical risks first, then report major and minor issues with concrete fixes.

Review Process

1. Identify scope — Determine exactly what to review.
2. Scan changes — Analyze against template-ts review categories.
3. Verify uncertain patterns — Use external lookup only when uncertainty remains.
4. Categorize findings — Classify as Critical, Major, or Minor.
5. Generate report — Produce an actionable review summary.
6. Run automated checks — Run repository-standard quality gates.

---

Step 1: Identify Scope

Determine scope in this order:

1. Use explicit user scope first. Review the exact files, PR, commits, or branch comparison provided by the user.
2. Infer recent commits by default when scope is missing. Use git log -5 --oneline and git diff HEAD~5..HEAD --stat when no scope was given and repository context is available.
3. Ask one precise scope question only when needed. Ask only when repository state is unavailable or multiple plausible scopes exist and inference would be unreliable.

---

Step 2: Apply Template-ts Review Categories

Use the full category checklist and examples in references/review-pattern-catalog.md.

Apply these category groups:

• TRPC patterns
• TanStack Router and Query patterns
• Code deduplication (DRY)
• Code quality and style conventions
• Security
• Performance
• Testing
• Effect patterns (when Effect code is in scope)

Load related skills when deeper specialization is required:

• trpc-patterns
• tanstack-frontend
• effect-ts
• scan-effect-solutions (for deep Effect audits)

---

Step 3: Verify Uncertain Patterns

Use lookup tools only when local codebase evidence is insufficient.

Use Exa to validate uncertain real-world usage patterns for external libraries or evolving APIs.

Use Context7 to confirm official documentation details (exact API names, version-specific behavior, deprecations).

Skip both when the repository already contains a clear canonical pattern.

---

Step 4: Apply Test Expectations Proportionally

Require tests for behavior changes.

Treat these as behavior changes:

• New or changed business logic
• API contract changes
• Query/loader behavior changes
• Security or authorization logic changes
• User-visible component behavior changes

Treat these as low-risk changes where new tests are optional:

• Documentation-only updates
• Comment-only updates
• Mechanical refactors with no logic change (for example rename-only, formatting-only, import reordering)

State test rationale explicitly in the final review summary.

---

Step 5: Run Automated Checks

Run bun run check when the repository uses the standard template-ts quality-gate script.

Run the repository-equivalent command set when a different convention is used (for example separate lint, typecheck, and test commands).

Capture command outcomes in the final report.

---

Severity Classification

CRITICAL (must fix before merge)

• Security vulnerabilities
• SQL injection or hardcoded secrets
• Missing authentication on protected endpoints
• Breaking changes to public APIs

MAJOR (should fix)

• Wrong TRPC v11 patterns (.useQuery instead of .queryOptions)
• N+1 database queries
• Missing prefetch causing slow page loads
• Manual types instead of RouterInputs/RouterOutputs
• Code duplication violating DRY

MINOR (consider fixing)

• Style inconsistencies
• Missing documentation
• Non-critical refactoring opportunities

---

Report Template

# Code Review Report

**Scope:** [What was reviewed]
**Date:** [Current date]

---

## CRITICAL ISSUES

[List with file:line, description, fix]

---

## MAJOR ISSUES

[List with file:line, description, fix]

---

## MINOR ISSUES

[List with file:line, brief description]

---

## TEST EXPECTATIONS

- Behavior-changing code paths covered: [Yes/No + details]
- Low-risk changes with test exemption: [Yes/No + rationale]

---

## AUTOMATED CHECKS

- Commands run: [List]
- Result: [Pass/Fail]

---

## POSITIVE OBSERVATIONS

- [Good patterns found]

---

## SUMMARY

**Assessment:** [APPROVE / NEEDS_WORK / REJECT]
**Next steps:** [Specific actions]

## Quick Stats

- Files reviewed: [N]
- Issues: Critical: [N], Major: [N], Minor: [N]

---

Assessment Criteria

APPROVE

• No critical issues
• Core TRPC and TanStack patterns are correct
• Repository quality-gate checks pass

NEEDS_WORK

• Major pattern violations exist
• Required tests are missing for behavior changes
• Performance issues impact reliability or UX

REJECT

• Security vulnerabilities exist
• Breaking changes are introduced without migration path
• Fundamental design flaws make the change unsafe to merge

---

Related Skills

• trpc-patterns — TRPC router patterns, procedures, error handling
• tanstack-frontend — Router, Query, Form patterns
• effect-ts — Effect services, layers, ManagedRuntime, error handling
• scan-effect-solutions — Deep Effect compliance scan
• production-troubleshooting — Performance investigation