---
name: wasp-review
description: Review code changes for correctness, clarity, and potential issues. Use when the user asks for a review, code review, PR review, or wants feedback on a diff or file.
---

# Rules

## Naming And Vocabulary

- Demand precise, informative names. Names must not misdirect, omit relevant behavior, or assume unavailable context.
- Make names accurately reflect what their declarations represent.
- Context is king: evaluate names within their scope and surrounding vocabulary.
- Use established codebase terminology consistently.
- Follow established naming conventions e.g. `is...` for booleans and `ensure...` for idempotent setup operations.
- Treat awkward names as evidence of design problems. If an accurate name becomes excessively long or complicated, inspect whether the declaration has too many responsibilities.
- Avoid vague names such as `data`, `info`, or unexplained single letters.

## Contracts And Interfaces

- Review names before implementation details. Poor names often expose deeper problems in decomposition and architecture.
- Declaration should be enough to understand, without the implementation. A function’s name, arguments, types, and contract should explain its behavior.

## Readability And Context

- Demand code to be easy to read. Understanding one section should not require reading the entire file.
- Review from the perspective of a developer with minimal reasonable context.

## Design And Architecture

- Treat `and` or `then` in a function name as a possible responsibility smell.
- Treat groups of similarly prefixed parameters as possible missing abstractions.
- Make sure the code is DRY. Introduce helpers for commonly repeated concepts.
- Identify hidden assumptions. Require assumptions to be enforced through types, runtime checks, or comments, in that order.
- Check for Effective TypeScript defined problems.
- Avoid NIH: check existing code and dependencies before introducing abstractions or helpers, share code once it has multiple consumers.

## Comments And Writing

- Prefer improving design or naming; use comments only when code cannot communicate enough.
- Remove comments that preserve session-specific context unnecessary to a fresh reader.
- Use comments only for information that names, arguments, and types cannot express.
- Remove comments that merely narrate obvious code or exhibit generated filler.
- Suggest pruning fluff and no-op sentences from prose.

## Code Smells

- **Primitive Obsession:** identify strings and primitives representing domain concepts that need dedicated types.
- **Shotgun Surgery:** flag one logical change scattered across unrelated files.
- **Divergent Change:** flag modules carrying several unrelated responsibilities.
- **Repeated Switches:** flag code that repeatedly handles the same cases in different places.
- **Speculative Generality:** reject abstractions and configuration without a current requirement.
- **Middle Man:** flag layers that only forward calls without enforcing a boundary or adding meaning.

## Other

- Check whether requested improvements justify their implementation cost.

# Findings And Reporting

- Make every finding actionable. Include the file and line, explain the problem, and suggest a concrete fix.
- Use code snippets when they make the problem or proposed fix clearer.