prune-cruft

name

prune-cruft

description

Surface and remove code that does not earn its keep — unnecessary memoization or caching, redundant type checks and casts, dead or unused code, over-engineered abstractions, and premature/unmeasured optimizations — in any language or framework. Use when the user wants to simplify a file or codebase, audit for cruft, cut needless memoization (useMemo/useCallback/React.memo, computed, lru_cache, hand-rolled caches), find dead code, drop redundant type guards, or asks "is this over-engineered" / "is this premature optimization".

Prune Cruft

Cut code that does not earn its keep. Default is the simplest code that solves the problem; anything more must justify itself with a real, current reason.

Glossary

• Cruft — code present without a current reason: unused, redundant, defensive past the point of need, or optimized for a non-problem.
• Earned its keep — has a real, current caller; a measured perf win; or a documented invariant. Hypothetical futures do not count.
• Load-bearing — removing it breaks something a real caller depends on today.
• Deletion test — imagine deleting it; if complexity vanishes it was a pass-through, if complexity reappears across callers it earned its keep.

Categories

Each category has a detail file with heuristics and do/don't examples. Read the relevant file before classifying a finding. Examples lean on TypeScript/React because that is where this cruft is most epidemic, but every category applies to any language.

• Unnecessary memoization — a memo or cache (useMemo/useCallback/React.memo, Vue computed, a lru_cache, a hand-rolled Map) without a real referential-stability or measured perf reason. See MEMOIZATION.md.
• Redundant type checks — runtime guards the type system already proves, double null checks, defensive ?. on non-nullable values, casts restating inference, double validation of already-validated data. See TYPE-NARROWING.md.
• Dead / unused code — exports, files, branches, params, flags, translation keys, enum members with no current consumer. See DEAD-CODE.md.
• Over-engineering — premature abstraction, single-implementation interfaces, factories of one, wrapper functions, options no caller flips, ports without a second adapter, unmeasured micro-optimizations. See OVER-ENGINEERING.md.

Principles

• Default to inline. Reach for a helper, wrapper, or abstraction only when removing it concentrates real complexity (deletion test).
• Types are guards too. If the type system already proves the case impossible, the runtime check is noise — and it lies about the contract.
• Measure before optimizing. No memoization, cache, or micro-opt without a measured runtime/CPU problem.
• One caller is not a pattern. Configurable knobs and ports need at least two real callers; rule-of-three for extraction.
• Pruning removes, it does not redesign. If a finding wants a new abstraction, escalate to improve-codebase-architecture instead.

Process

1. Scope

Confirm what to scan: a file, a directory, a feature slice, or the whole app. Do not boil the ocean — pick a bounded surface so findings stay reviewable.

2. Scan

Walk the scope and tag findings against the four categories. For each candidate record:

• Where — file + line range
• Category — memoization / type-narrowing / dead-code / over-engineering
• Why it is cruft — concrete reason, not vibes — cite the heuristic from the detail file
• Risk if removed — none / low / needs callsite check / load-bearing

When a finding is ambiguous, prefer "needs callsite check" over deleting blind. For dynamic lookups, generated code, and cross-package exports, verify across the whole codebase (every app/package in a monorepo), not just the current file.

3. Present findings

Group by category, highest confidence first. Use this shape per finding:

• File — @absolute/path:start-end
• Smell — one line
• Proposed change — what to delete or replace with
• Reasoning — which heuristic from the category file applies
• Verification — typecheck / lint / test command, or "visual check on route X"

Do NOT bulk-apply yet. Ask the user which findings to action, or if they want a category swept at once.

4. Apply, then verify

Apply approved changes minimally — prefer deletion over rewrites, single-line edits over refactors. After each cluster:

• Run the project's typecheck or build (e.g. tsc --noEmit, cargo check, go build, mypy).
• Run lint / formatter on touched files.
• Run any tests that cover the touched modules.
• For UI changes, name the route(s) the user should re-click.

If a deletion breaks types, do NOT add casts to silence it — that is just relocating cruft. Fix the contract or revert the deletion.

5. Stop conditions

Stop when:

• Remaining findings are load-bearing or contested.
• A change would require redesigning a module — escalate to improve-codebase-architecture.
• The user signals enough.

Never invent new abstractions while pruning. Never weaken or delete tests to make a deletion typecheck — that hides regressions instead of preventing them.