/cleanup

name: cleanup
description: Review and clean up the given file(s)/folder(s)/module(s): rate organization, find dead code, duplication, coupling, over-engineering, deep nesting, structural issues, and bad comments, then produce and execute a phased refactor plan. Trigger on "clean up X", "review and refactor X", "rate the code in X", "code quality review of X", "fix the comments in X".
metadata:
  version: "1.2"

Code Cleanup

Review a target path (file, folder, module, or feature), then fix what you found. Judge everything against the project's own written rules (CLAUDE.md, rules files, lint config), not general taste. The argument is the target path(s). If none given, ask.

Limits: one review pass, one implementation pass, one question to the user. Do not add more.

Findings list

One file in the scratchpad, one line per finding: `id | category | file:line | claim | evidence | status`. Status is CONFIRMED, UNCERTAIN, or KEPT. For any "unused" or "dead" claim, the evidence is the search that proved it. Search for indirect uses too: keys built from strings, `obj[key]` lookups, translation keys assembled at runtime. A claim without a search stays UNCERTAIN. KEPT records what was checked and deliberately left alone.

Process

1. Map the target (you, no agents)

• List the target's files with line counts, largest first.
• If the project has a dead-code tool (knip, ts-prune, depcheck, an unused-imports lint rule), run it on the target first and seed the findings list from its output. Manual searching then covers only what the tool cannot see: keys built at runtime, translation keys, response fields.
• Search once for files outside the target that import from it. The names they import are the public API that moves and renames must keep working.
• Note connected files: routes or pages that render the target, providers, query functions and keys, locale files, docs or feature index entries. Search them for references only. Do not review them in full.
• Write a 5-line summary of the project rules from the docs already in context: file size limit, naming, comment policy, framework habits (if the framework already memoizes, as React Compiler does, manual memoization counts as an issue), and the check commands (typecheck, lint, tests). Paste it into every agent prompt.

2. Review

Read each target file once, fully. Record every finding as a line in the findings list. Skip a bullet only when it cannot apply.

**Unused code**: exports nothing imports, props never used or always given the same value, state set but never read, unreachable branches, unused translation keys, assets, or style properties, commented-out code, wrappers with a single caller that add no behavior, generics only ever used with one type, a config layer read from one place, query functions or keys nobody imports, interfaces, base classes, or strategy patterns with a single implementation, tests for removed code, duplicated tests, unused mocks, outdated docs or feature index entries.

**Repeated code and mixed patterns**: near-identical functions, components, markup, or style blocks; data reshaping that redoes an existing util (check the project's utils first); copy-pasted loading, empty, and error blocks; the same constant written inline in several places; two ways of solving one problem inside the target (switch all to the one the project uses most); files past the size limit or doing too many jobs.

**Control flow and function shape**: nested or chained ternaries, deep if/else that early returns would flatten, `else` after `return`, `if (x) return true; else return false`, negated conditions with swapped branches; boolean flag parameters that switch behavior (split the function), five or more parameters, different return shapes on different paths, one-line helpers called once (inline them); sequential awaits with no dependency between them, `.then` chains mixed with `await`, try/catch that only rethrows, `async` on functions that never await; `x ? x : y` where `??` fits, the same default applied at several layers, `null` and `undefined` both used for absence.

**Structure and data flow**: props passed through layers unchanged, many props that belong together in one object, the same data fetched or computed in several places, one request per item where a batch request exists, effects that copy data into state when it could be computed directly, lists that grow with no limit or pagination, a large library imported for one function, errors caught and ignored, missing error, loading, or empty states, timers or subscriptions never cleaned up, race conditions from outdated closures or missing awaits, `renderSomething()` helpers that should be components, markup nested four or more wrapper levels deep, importing another feature's internals, circular imports.

**Comments, types, naming, text**: comments that describe the next line, restate the name, mention tasks or PRs, or mark removed code; divider comments like `// ---- Helpers ----`; long comments that should be one line saying why; comments explaining what confusing code does (rename or extract instead, then delete the comment); comments that contradict the code. Names that promise one thing while the code does another, booleans that don't read as yes/no questions, one concept under two names in the module, abbreviations nobody else uses. `any` or `unknown` casts, `!` assertions where a type check would do, anonymous object types written inline in signatures, hand-written types that duplicate what the code already infers or generates. Files sitting in the folder root that belong in a subfolder, filename prefixes that repeat the folder name, index files that only re-export. Hardcoded user-facing text, translation keys missing in some locales, missing alt or aria attributes. Anything that breaks the project rules summary.

**Packages and API endpoints** (only when the target owns a package manifest, endpoints, or config): packages with zero imports, two libraries