name: anti-overengineering-review
description: On-demand review that hunts ONLY over-engineering and reports what to delete - reinvented standard library, unneeded dependencies, speculative abstractions, dead flexibility. Three one-shot modes, none apply fixes: diff review, whole-repo audit, and an enigma: debt-marker ledger. Use when the user says "review for over-engineering", "what can we delete", "is this over-engineered", "simplify review", "audit this codebase", "find bloat", "what did we defer", "list the shortcuts", or "what did we mark to do later". Complements code-review-policy (which owns correctness, security, and performance); this one only cuts complexity.
Anti-Overengineering Review
On-demand complexity hunting. This skill finds what to delete and reports it;
it never applies the fixes. Correctness bugs, security holes, and performance go
to a normal review pass (code-review-policy owns those) - this one only cuts
complexity. The build-time discipline that prevents the bloat in the first place
lives in anti-overengineering-policy.
Pick the mode from the request:
- Review - a diff or set of changes (default).
- Audit - the whole repository.
- Debt - harvest the
enigma: shortcut markers into a ledger.
Tags (Review and Audit)
One line per finding. Each is tagged by what kind of cut it is:
delete: dead code, unused flexibility, speculative feature. Replacement: nothing.stdlib: hand-rolled thing the standard library ships. Name the function.native: dependency or code doing what the platform already does. Name the feature.yagni: abstraction with one implementation, config nobody sets, layer with one caller.shrink: same logic, fewer lines. Show the shorter form.
Review (diff)
Format: L<line>: <tag> <what>. <replacement>., or <file>:L<line>: ... for
multi-file diffs. The diff's best outcome is getting shorter.
Bad: "This EmailValidator class might be more complex than necessary; have you
considered whether all these rules are needed?"
Good:
L12-38: stdlib: 27-line email validator class. "@" check in one line; real validation is the confirmation mail.L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.L30-44: shrink: manual loop builds a dict. dict(zip(keys, values)), 1 line.
End with the only metric that matters: net: -<N> lines possible. Nothing to
cut: Lean already. Ship.
Audit (repo-wide)
Review, applied to the whole tree instead of a diff. Same tags, ranked biggest
cut first. Hunt: dependencies the stdlib or platform already ships,
single-implementation interfaces, factories with one product, wrappers that only
delegate, files exporting one thing, dead flags and config, hand-rolled stdlib.
Format: <tag> <what to cut>. <replacement>. [path], ranked. End with
net: -<N> lines, -<M> deps possible. Nothing to cut: Lean already. Ship.
Debt (marker ledger)
Every deliberate shortcut left by anti-overengineering-policy is marked with an
enigma: comment naming its ceiling and upgrade path. Collect them so a
deferral cannot quietly become permanent.
Scan the repo for the markers, skipping node_modules, .git, and build output:
grep -rnE '(#|//) ?enigma:' .
(Add other comment prefixes if the stack uses them.) The comment prefix keeps
prose that merely mentions the convention out of the ledger.
One row per marker, grouped by file:
<file>:<line> - <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.
Pull the ceiling and the trigger straight from the comment (the convention is
enigma: <ceiling>, <upgrade path>). Any marker that names no upgrade path or
trigger gets a no-trigger tag - those are the ones that silently rot. End with
<N> markers, <M> with no trigger. Nothing found: No enigma: debt. Clean ledger.
Boundaries
- Complexity only. Correctness, security, and performance go to code-review-policy.
- A single smoke test or assert-based self-check is the anti-overengineering minimum, not bloat - never flag it for deletion.
- Lists findings; applies nothing. One-shot report. Ask before writing a ledger to a file (e.g.
OVERENGINEERING-DEBT.md).
