Codebase Review

Perform a systematic review of a codebase and produce a priority-ordered action list grouped by severity. This skill is optimized for full-stack web applications (TypeScript/Go/React/Next.js/PostgreSQL/Redis) but applies to any project type.

Step 1: Orient Yourself

Before reading any code, understand the shape of the project.

- List the root directory
- Read README.md (or equivalent) if present
- Check TODO.md (or equivalent) if present for known issues
- Read any config files at the root: package.json, go.mod, pyproject.toml, Cargo.toml, etc.
- Identify: language(s), framework(s), infrastructure, entry points
- Note the directory structure — are there clear separations (api/, components/, lib/, etc.)?

Ask the user if anything is unclear about scope: which branch, which service, specific areas of concern. Do this before diving into files.

Step 2: Build a Review Plan

Based on Step 1, decide which files and directories to examine. Prioritize:

1. Entry points and routing (main.go, app/layout.tsx, server.ts, index.ts, etc.)
2. Authentication and authorization logic
3. Database access layers and query patterns
4. API handlers and middleware
5. Environment/config handling
6. Key business logic modules
7. Shared utilities and types
8. Test files (presence, not just content)

For large codebases (>50 files), sample strategically — read 2–3 files per category above rather than exhaustively. Note what you sampled vs. skipped.

Step 3: Run the Four Review Lenses

Examine the code through each lens below. Take notes as you go — you will synthesize at the end.

Lens A: Code Quality & Patterns

Look for:

• Duplication: Logic repeated in multiple places that should be extracted
• Dead code: Unused functions, variables, imports, routes, or feature flags
• Inconsistency: Mixed naming conventions, inconsistent error handling styles, mixed async patterns
• Complexity: Functions doing too many things; deeply nested conditionals; long files
• Type safety: Missing types, overuse of any, unvalidated external data
• Error handling: Errors swallowed silently, missing fallbacks, untyped catch blocks
• Magic values: Hardcoded strings/numbers that should be constants or config

Lens B: Security

Trace trust boundaries and verify relevant controls rather than treating this as a generic checklist. Look for:

• Secrets and sensitive data: Keys, tokens, passwords, private data, or internal details exposed through source control, browser bundles, logs, errors, fixtures, caches, or metadata
• Input and output boundaries: Missing server-side validation, unsafe output encoding, SQL injection, XSS, path traversal, command injection, unsafe deserialization, and malformed external responses
• Authentication and sessions: Unprotected routes, session fixation, weak cookie settings, insecure account recovery, missing reauthentication for sensitive actions, and unsafe token handling
• Authorization: Missing object-level, tenant-level, ownership, role, database, or service-boundary checks; never treat a hidden client control as authorization
• Request forgery and redirects: CSRF, SSRF, open redirects, untrusted callback URLs, and insufficient outbound-request restrictions
• Files and content: Unsafe uploads, filenames, content types, storage permissions, downloads, image processing, and user-supplied rich content
• Webhooks and repeated work: Missing signature verification, replay protection, idempotency, duplicate-processing controls, and timestamp tolerance
• Abuse and resource controls: Missing rate limits, quotas, pagination, size limits, or cost controls on public, expensive, or privileged operations
• Browser and transport policy: Overly permissive CORS, CSP, framing, referrer policy, HSTS, mixed content, and cache policy where applicable
• Cryptography: Weak password hashing, inappropriate general-purpose hashes, insecure randomness, invalid JWT assumptions, or custom cryptographic protocols
• Environment and deployment boundaries: Committed environment files, missing startup validation, debug behavior in production, excessive database privileges, and unsafe row-level-security or service-role usage
• Dependency and supply-chain risk: Findings supported by configured scanners, authoritative advisories, unsupported runtimes, install scripts, or concrete compatibility evidence. Do not report age alone as a vulnerability.

For a security-focused review, follow relevant flows end to end and state which trust boundaries were not verified. Never print secret values.

Lens C: Performance

Look for:

• N+1 queries: Loops that issue database queries per iteration
• Missing indexes: Queries filtering on columns that are likely unindexed
• Unbounded queries: SELECT * or queries without LIMIT on large tables
• Blocking operations: Sync I/O in async contexts, missing concurrency where it's warranted
• Caching gaps: Repeated expensive operations (API calls, DB reads) with no caching layer
• Bundle size signals: Large unnecessary imports on the frontend (importing full libraries for one utility)
• Memory leaks: Event listeners or subscriptions not cleaned up; large objects held in module scope

Lens D: Architecture & Structure

Look for:

• Coupling: Business logic mixed into route handlers or UI components; hard-to-test code
• Layer violations: DB calls in the frontend, UI logic in the backend
• Missing abstraction: No repository/service layer where one would help; repeated raw queries
• Config management: No central config validation; environment differences not handled cleanly
• Observability: No logging, no structured error reporting, no health check endpoints
• Scalability signals: Stateful design that would break under horizontal scaling; no graceful shutdown handling

Do not recommend repository/service layers merely because they are absent. Require evidence of harmful coupling, duplication, or difficult testing first.

Step 4: Run Bounded Verification

Discover and run existing checks relevant to the review scope:

• Behavior-focused tests
• Type checking
• Linting
• Production build
• Backend tests or static analysis
• Configured dependency and security scanners
• Focused runtime or browser checks when source inspection cannot verify behavior

Run focused checks before broad suites. Do not install dependencies, change versions, alter configuration, or bypass controls merely to make verification run.

Report each attempted check as PASS, FAIL, BLOCKED, or NOT RUN, with a concise reason. Distinguish pre-existing failures from issues introduced by current work when evidence permits. Verification supports the review but does not replace code-path analysis.

Step 5: Record Detailed Findings

Updating TODO.md is intentional behavior and is the only default file mutation performed by this skill.

When findings require a TODO.md update, invoke update-docs and follow its canonical structure. Treat TODO.md as the authoritative detailed review record.

• Add only confirmed unresolved findings not already represented.
• Record the evidence, impact, affected files, recommended fix, and verification criteria there.
• Merge duplicate findings.
• Move verified completed items to the Completed section.
• Mark invalid or superseded items as [STALE] with an explanation.
• Preserve historical items.

Do not repeat the full finding descriptions or fixes in the chat response.

Step 6: Produce a Concise Chat Summary

Return a short, priority-ordered summary using this format:

### Review summary

[One sentence describing the overall state and dominant risk.]

**Findings:** N critical, N high, N medium, N low

- **Critical:** `[CRIT-1] Short title` (`path/to/file.ts:line`)
- **High:** `[HIGH-1] Short title` (`path/to/file.ts:line`)
- **Medium:** `[MED-1] Short title` (`path/to/file.ts:line`)
- **Low:** `[LOW-1] Short title` (`path/to/file.ts:line`)

**Verification:** [Concise PASS, FAIL, BLOCKED, and NOT RUN results.]

**Top priority:** [The single most important next action.]

**Scope:** [What was reviewed or sampled, and what was out of scope.]

**Documentation:** Detailed findings were recorded in `TODO.md`.

• Omit empty severity lines.
• Keep each listed finding to its identifier, title, and primary location.
• Include all finding titles when there are ten or fewer. For larger reviews, list the ten highest-priority findings and state that the remainder are in TODO.md.
• Do not include code snippets, full explanations, fixes, or completed-item history in chat unless the user asks.
• If no documentation update was needed, state that TODO.md was not modified.

Behavior Rules

• Be specific. Every finding must reference a file. Avoid generic advice like "add more tests" unless you have observed a concrete gap.
• Be honest. If something is solid, say so. Do not pad the list with non-issues to appear thorough.
• Scope clearly. If you sampled rather than read everything, say so in the output: "Based on review of X, Y, and Z — full review of [area] was out of scope."
• Limit mutations. Do not modify application code during the review. Updating or creating TODO.md as specified above is the only default file mutation.
• No inline code comments. Keep detailed findings in TODO.md and the concise index in the chat report, not as comments inserted into application code.
• Adjust for stack. For TypeScript projects, check for any, missing zod/validation, and improper use of as. For Go, check for ignored errors, goroutine leaks, and missing context cancellation. For React/Next.js, check for missing Suspense boundaries, improper data fetching patterns, and client/server component misuse.