Skip to content

tobihagemann/turbo / claude/skills/review-code

review-code

Verified

Review code for bugs, security, API misuse, consistency, simplicity, or test coverage, with peer review in parallel. Use when the user asks to "review my code", "check for bugs", or "security audit".

references/simplicity-review.md

View on GitHub
# Simplicity Review Reference

## Review Instructions

Focus on single-file simplicity: scope, reuse, quality, efficiency, and clarity issues that surface within an individual file or a small set of changes.

For scope, trace the callers of the code you propose deleting and confirm nothing depends on the behavior being removed. Judge "unrequested" against what the reviewed change set out to do; anything it was explicitly asked for is in scope by definition. Ground the finding in what the code does rather than in how much of it there is.

For reuse, identify analogous utilities, helpers, or shared modules elsewhere in the project before suggesting a rewrite. Common locations are utility directories, shared modules, and files adjacent to the changed ones.

## What to Review

### Scope

- **Unrequested machinery** — an abstraction with one implementation, a configuration point with one caller, a factory for one product, a wrapper that only delegates, scaffolding for an anticipated requirement; delete it rather than simplify it
- **Unreachable defensive code** — a branch, guard, retry, or fallback for a state the surrounding code's own constraints rule out; when the callers cannot produce the input, the handling for it is dead on arrival
- **Reinvented standard library or platform feature** — hand-rolled logic the language's standard library or the target platform already ships, or a new dependency for what an already-installed one covers; name the replacement
- **Superseded implementation kept** — a new version added beside the one it replaces when every caller of the old version is inside this repository, often marked by a suffix such as `V2` or `New`; migrate the callers and delete the old version

### Reuse

- **Duplicate functionality** — new functions that duplicate existing utilities, unless written to replace them; suggest the existing function to use instead
- **Inline logic that could use an existing utility** — hand-rolled string manipulation, manual path handling, custom environment checks, and similar patterns where a utility already exists

### Single-File Quality

- **Redundant state** — state that duplicates existing state, cached values that could be derived, reactive subscriptions that could be direct calls
- **Parameter sprawl** — new parameters added to a function instead of generalizing or restructuring existing ones
- **Copy-paste with slight variation** — near-duplicate code blocks within the same file that should be unified with a shared abstraction
- **Leaky abstractions** — exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
- **Stringly-typed code** — raw strings used where constants, enums, or dedicated types already exist in the codebase
- **Silenced type errors** — a cast, suppression directive, or non-null assertion that silences a type-checker error with no adjacent check or comment establishing the invariant that makes it safe
- **Silent fallbacks** — a catch or fallback value that turns a failure of the primary path into a plausible-looking result, such as an empty collection or a default value, without surfacing the failure, when neither a stated requirement nor the surrounding design calls for degraded behavior; surface the failure rather than remove the handling
- **Unnecessary wrapper nesting** — container elements or wrapper layers that add no structural or layout value

### Efficiency

- **Unnecessary work** — redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns
- **Algorithmic complexity** — nested iterations, repeated linear searches replaceable by sets/maps, missing early exits
- **Missed concurrency** — independent operations run sequentially when they could run in parallel
- **Hot-path bloat** — new blocking work added to startup or per-request hot paths
- **Refresh cadence** — work triggered more often than its result can change, such as refetching rarely changing data on every event, request, or timer tick
- **Unnecessary existence checks** — pre-checking file/resource existence before operating (TOCTOU anti-pattern); operate directly and handle the error
- **Memory** — unbounded data structures, missing cleanup, resource leaks, and long-lived closures or callbacks that capture, and so keep alive, more state than they use; narrow the capture to the state the closure uses
- **Overly broad operations** — reading entire files when only a portion is needed, loading all items when filtering for one

### Clarity and Standards

- **Project standards** — coding conventions not followed (import sorting, naming conventions, component patterns, error handling patterns, module style). Beyond the auto-loaded instruction files, walk each directory that is an ancestor of a changed file, from the project root down, and read its `CLAUDE.md` and any file those instructions import — a directory's file governs only the files at or below it. Flag a violation only when you can quote the exact rule and cite what breaks it: the offending line, or the location where a required element is missing. Name the file the rule came from
- **Unnecessary complexity** — deep nesting, unclear variable or function names, nested conditionals 3+ levels deep (ternary chains like `a ? x : b ? y : ...`, nested if/else, or nested switch — flatten with early returns, guard clauses, a lookup table, or an if/else-if cascade), redundant boolean comparisons (e.g., `x == true` instead of `x`)
- **Unclear code** — overly compact one-liners that sacrifice readability; explicit code is better than clever code
- **Over-simplification** — too many concerns combined into a single function or component, helpful abstractions removed that were aiding code organization, "fewer lines" prioritized over readability
- **Dead weight** — code no longer reached by any path; variables, imports, or parameters the change orphaned; and debug prints or logging left behind from tracing execution

### Altitude and Fix-Depth

- **Special case on shared infrastructure** — a narrow branch, flag, or conditional added to a shared mechanism to handle one case, where generalizing the mechanism removes the need for the special case; name the generalization
- **Shallow fix at the symptom** — a change applied at one call site that the same shape will require again at the next similar site; prefer addressing the shared root
- **Wrong layer** — logic placed in a caller, wrapper, or leaf when it belongs in the shared layer all paths flow through, or pushed into shared infrastructure when it is specific to one caller

### Comments and Documentation

- **Asserts a contract the code does not enforce** — states what is handled, excluded, guaranteed, or left untouched, where the code beneath it does something else; verify each such claim against the code rather than reading it as intent, then propose correcting the comment or flag the missing enforcement when the stated contract is the desired one
- **Positional reference that no longer resolves** — carries an ordering or directional word such as "first", "above", or "below" whose target the code has since moved; verify the word still picks out what it names, then propose correcting it to name what it refers to directly, or deleting it when nothing else in the comment survives
- **Restates code, signature, or name** — paraphrases the immediately-following statement or multi-statement block; doc blocks whose text translates a declaration's name; doc blocks above a declaration whose prose elaborates the name and signature without adding rationale; parameter/return descriptions that only echo names and types. Non-obvious constraints (size, units, ranges, preconditions) stay; drop the wrapping parameter/return/error enumeration when no entries survive trimming. Where an instruction file or the documentation tooling's configuration requires that declaration to carry documentation, keep what the requirement covers and flag only entries that describe the code wrongly
- **History or change narration** — references to PRs, tickets, prior behavior, recent changes, "fixed by"/"previously did X"/"no longer Y" framing, or session-narrative voice ("turns out", "discovered", "we found that"); state the current invariant only — past behavior belongs in git history, and session-derived lessons about tooling belong in auto memory or project instructions. Change narration also appears in invariant form: a sentence that reads as a rule but only carries meaning as a contrast with the code's prior behavior, and that you would not write if the code had been greenfield from day one
- **Cross-references that decay** — names the caller ("used by X", "called from Y"), or task/flow/feature-flag context the code was added for ("added for the Y flow", "for the rollout"); delete — caller relationships belong in the call graph, feature context in the PR description
- **Framework or stdlib explainers** — describes what a well-known language keyword or library construct does
- **Low-value section banners** — banners that don't section anything, or that restate what an access modifier or naming convention already conveys
- **Overgrown rationale** — a comment that captures real WHY but in more lines or concerns than the rationale requires; tighten to one sentence per concern, split bundled concerns to their decision points, or lift shared rationale to a design doc or commit message
- **Compensates for unclear code** — a comment that exists because the code is hard to read; flag the underlying code as a refactor opportunity (rename, extract, restructure) rather than tightening the comment
- **Markdown status-update voice** — for markdown changes in the diff, prose framed as recent updates or transitions; rewrite as timeless current-state prose. It also appears in invariant form: a sentence that reads as a rule but only carries meaning as a contrast with the design it replaced, and that you would not write if the project had always worked this way

## Determination Criteria

Flag an issue only when ALL of these hold:

1. The issue meaningfully impacts readability, maintainability, correctness, or performance
2. The issue is discrete and actionable
3. A specific fix is obvious (reuse existing utility X, remove redundant state Y, collapse nested wrapper Z)
4. The fix does not demand rigor beyond what exists in the rest of the codebase
5. The author would likely accept the fix if aware of it, OR the finding challenges a deliberate choice with evidence of a simpler alternative

## Priority Levels

- **P0** — Severe efficiency problem on a hot path, or a reuse miss that duplicates a load-bearing utility
- **P1** — Clear duplication, leaky abstraction, unrequested machinery, or efficiency issue with meaningful impact
- **P2** — Moderate clarity, efficiency, or reuse opportunity
- **P3** — Minor style or readability nit

## What to Ignore

- Style-only differences that do not obscure meaning or violate documented standards
- Micro-optimizations with no measurable impact
- Input validation at trust boundaries, error handling that prevents data loss, security controls, and accessibility affordances; these outrank the Scope bullets when both apply to the same code
- Comments that capture a load-bearing constraint the code itself cannot express — a hidden constraint or invariant, a workaround for a specific bug (ideally with a reference), a non-obvious performance characteristic, a pointer to a spec or RFC section, or behavior that would surprise a future reader. Greenfield test: would you write this comment if the code had been greenfield from day one?

**Extra metadata:** `**Category:** <scope | reuse | quality | efficiency | clarity | altitude | documentation>`

**Verdict label:** `Simplicity: <clean | issues found>`
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall