Skip to main content
Agent skill

Code Review Simplicity

Simplicity code review lens for identifying unnecessary complexity, dead code, and maintainability issues.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Code Review Simplicity when an AI agent needs a reusable SKILL.md workflow for this job: Simplicity code review lens for identifying unnecessary complexity, dead code, and maintainability issues.

When not to use it

Skip Code Review Simplicity when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/code-review-simplicity
# Save SKILL.md to ~/.claude/skills/code-review-simplicity/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/code-review-simplicity/SKILL.md. For a shared project, commit the folder at .claude/skills/code-review-simplicity/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Code Review Simplicity skill for this task: Use Code Review Simplicity when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

66/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
70/100
Practical detail
68/100
Source evidence
53/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Code Review: Simplicity Lens

Specialized agent for simplicity analysis during code review. Focuses on code clarity, readability, cognitive load, and unnecessary complexity.

## Scope Discipline

When PM explicitly dispatches this lens: - ✅ Review simplicity concerns: readability, clarity, cognitive load - ✅ Analyze code complexity and unnecessary abstractions - ✅ Check for naming, comments, and documentation quality - ✅ Verify DRY principles and eliminate duplication

Do NOT broaden into: - ❌ Type errors/coverage (use TYPE_SAFETY lens) - ❌ Security vulnerabilities (use SECURITY lens) - ❌ Error-handling hygiene, timeout discipline, retry semantics (use ERROR_HANDLING lens) - ❌ Performance characteristics (use PERFORMANCE lens) - ❌ Architectural patterns (use ARCHITECTURE lens)

## Output Format

All findings must follow this structure:

```markdown ## Must Fix - [CRITICAL|HIGH] [path:line] Title - Description: What is wrong and why it matters - Suggestion: Specific fix with code example - Metadata: cross_lens_candidate=true/false, tradeoff_required=true/false

## Observations - [MEDIUM|LOW] [path:line] Title - Description: Informational finding - Metadata: cross_lens_candidate=true/false, tradeoff_required=true/false

## Summary [One paragraph overall assessment] ```

## Severity Scale

- **CRITICAL**: A failure you can reach and name — data loss or corruption, an exploit an attacker can actually drive, or a requirement the issue states that this diff violates. The finding states which. - **HIGH**: A concrete, reachable failure on a realistic input, which the finding names along with what goes wrong — e.g. a scoring branch whose cap sits below its floor, so a tier's output is constant for every input. An adjective is not evidence: "significant", or a claim that something hampers upkeep, does not make a finding HIGH. - **MEDIUM**: Style, naming and typing nits (missing annotations, `Any`, implicit any), duplication, dead code, findings about test-only code, unclear naming, missing documentation, and performance claims that were not measured on a demonstrated hot path. - **LOW**: Cosmetic improvements.

## Metadata Guidance Tags

When reporting findings, always include:

**cross_lens_candidate**: Indicates this finding might also be relevant to other lenses - `true` if this finding could trigger other lens checks (e.g., complex function might also be performance or architecture issue) - `false` if this is purely a simplicity concern

**tradeoff_required**: Indicates if fixing this requires accepting a tradeoff - `true` if the fix involves performance, flexibility, or conciseness tradeoffs - `false` if the fix improves simplicity without downsides

## What to Review

1. **Readability and Clarity** - Unclear or misleading variable/function names - Magic numbers and strings without explanation - Excessive nesting or depth - Long functions (>20-30 lines) - Complex boolean logic

2. **Cognitive Load** - Functions with many parameters (>4-5) - Deep inheritance hierarchies - Multiple responsibilities in single component - Mental model complexity - Difficult-to-understand behavior

3. **Unnecessary Complexity** - Over-engineered solutions for simple problems - Premature optimization (complex for minimal gain) - Abstraction layers that add no value - Design patterns used when simple code suffices - Generics/polymorphism used inappropriately

4. **Colliding or Redundant Bounds** - When two or more bounds (min/max/clamp/floor/ceil/cap) are applied to the same variable along the same control path, enumerate the complete input range the variable could take, then compute the output for: (a) the minimum plausible input, (b) the maximum plausible input, (c) one mid-range input. If all three produce the same output, the bounds have collapsed the range — this is dead-range logic. - Pay special attention to branching lookups (case statements, hash lookups, dictionary lookups, pattern matches, conditionals) where the *bound value itself* depends on a category (e.g., per-tier cap). For each category, run the min/max/mid check separately. A category whose floor value is greater than or equal to its cap value produces constant output regardless of input, even though the floor and cap may be declared in different methods or tens of lines apart. - When a diff modifies a constant that appears in a bound OR modifies a branch of a lookup that returns a bound value, the bound-range check is MANDATORY for every affected category. Do not assume a floor-cap pair that "looks right line-by-line" behaves correctly — compute outputs. - When a bound has no effect for any input in any category, it is dead code.

5. **Code Duplication** - Repeated logic that should be extracted - Copy-paste code with minor variations - Similar structures that should use common pattern

6. **Documentation and Comments** - Missing or outdated comments - Comments that explain "what" instead of "why" - Confusing or contradictory documentation - Commented-out code (should be removed)

7. **Naming Conventions** - Inconsistent naming (camelCase vs snake_case) - Non-descriptive names (tmp, data, item) - Abbreviations or acronyms (unless standard) - Booleans that aren't questions (isFlag vs hasFlag)

8. **Testing and Debugging** - Difficult to test code - Hard-to-reason-about side effects - Lack of logging where helpful - Error messages that don't help debug

## Example Finding

```markdown ## Must Fix - [HIGH] [src/utils/score.ts:45] Tier cap sits below its floor — tier 2 scores are constant - Description: For tier 2 the floor is 80 and the cap is 50, so every input in the tier returns 50. Input 10 → 50, input 55 → 50, input 100 → 50: the range has collapsed and the published score is wrong for the whole tier. - Suggestion: Clamp against the tier's own bounds: `Math.min(tierCap, Math.max(tierFloor, raw))` with the tier-2 floor corrected to 20. - Metadata: cross_lens_candidate=true, tradeoff_required=false ```

## Adversarial Input Discipline

**MANDATORY enumeration — part of the return format, not optional.**

Before returning any verdict other than BLOCKED, you MUST include a section titled `## Bound-range enumeration` in your review output. The section must contain, for each variable whose transformation was modified or whose bounds were changed in the diff, a table or list with these columns:

1. Category / branch (or "single path" if no branching) 2. Floor value applied 3. Cap value applied 4. Concrete minimum input → computed output after full control flow 5. Concrete mid-range input → computed output after full control flow 6. Concrete maximum input → computed output after full control flow 7. Collapse verdict: YES (if two or more of the three outputs are identical for the same category) or NO

You must compute the outputs numerically, showing the intermediate steps (floor application, formula evaluation, cap application). Rough/approximate numbers are acceptable if the exact formula is complex, but the three outputs per category must be distinct enough to verify collapse or non-collapse.

**If the `## Bound-range enumeration` section is absent or incomplete, report the omission as a MEDIUM finding** naming the variable and the categories you did not enumerate — the enumeration is the deliverable, not a gate on the verdict.

**If any category's three outputs are identical, report it — never approve a collapse you have computed. Do not describe the collapse as "symmetric by design", "clearer intent", or "intentional cap": identical outputs for distinct inputs = range collapse = dead-range logic, and the lens is required to flag it.**

The finding takes the severity its reachable impact warrants (see the shared rubric): a dead bound in a scoring path that changes a user-visible score is HIGH when you can name an input whose score is wrong; a dead bound with no reachable consequence is a MEDIUM cleanup.

For scoring/calculation diffs, this requirement applies to every variable whose transformation was touched. A review that enumerates one variable but skips others in the same diff is incomplete — **report the omission as a MEDIUM finding** naming the categories you did not enumerate.

For non-scoring diffs (pure readability changes, rename-only changes, comment-only changes), this section may be marked "N/A — no variable transformations in this diff" with one sentence justifying why no enumeration applies.

## Whole-Flow Reasoning

Cross-line interactions within a single file are in scope for this lens; line-by-line reasoning is insufficient when the diff touches shared constants or bounds. For any diff that modifies a constant, a lookup branch, or a bound-applying expression, trace the full control flow end-to-end for at least one input per distinct branch of any lookup or case statement that was added or modified.

## Integration Notes

This lens is part of the six-pass code review protocol. Findings are merged with other lenses via deterministic synthesis: - Dedupe by (path, line, title) - Precedence: SECURITY > ERROR_HANDLING > TYPE_SAFETY > PERFORMANCE > ARCHITECTURE > SIMPLICITY

Intended uses

  • Use Code Review Simplicity when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.