code-review

name	code-review
description	Sensibility and complexity review of pending changes. Use when the user wants to audit a diff or changeset for unnecessary complexity, poor comments, or fragile constraints.
allowed-tools	Bash, Read

Review the pending changes (or the files specified by the user) for the issues below. Report findings grouped by severity. Propose concrete fixes; don't just describe problems.

What to look for

Unnecessary complexity

• Code that reimplements something the framework or stdlib already provides
• Abstractions added speculatively (no current caller, no current need)
• Workarounds that outlived the problem they solved
• Config or build logic that belongs in a simpler place (e.g. hand-rolled .env parsers when the framework auto-loads .env files)

Comment quality

Default is no comments. Flag comments that:

• Describe WHAT the code does (readable from the code itself) — remove them
• Are stale (describe behavior that no longer exists)
• Are placeholders or TODOs with no owner

Keep comments that explain WHY: a hidden constraint, a non-obvious invariant, a workaround for a specific upstream bug, or behavior that would surprise a future reader.

Fragile constraints

Things that will silently break if a future developer removes them without knowing why:

• Flags in scripts that seem optional but are required (e.g. --webpack to make assetPrefix work in Next.js dev)
• Order dependencies between steps
• Version pins with no explanation
• Feature flags left permanently on/off

For each fragile constraint, check: is the WHY documented near the code? If not, that's a finding.

Duplication

• Logic copied across files that should share a single source of truth
• Constants defined in multiple places

Over-engineering

• Error handling for cases that cannot happen at runtime
• Validation of data that is already trusted (internal APIs, typed inputs)
• Backwards-compatibility shims for code that has no other callers

How to report

For each finding:

• State the file and line range
• Classify: complexity, comment, fragile, duplication, or over-engineering
• One-sentence description of the issue
• Proposed fix (inline if small, described if larger)

End with a summary: total findings, which are safe to fix now vs. need discussion.