code-simplification

Code Simplification

Review code for unnecessary complexity, ungrounded implementation choices, and safe reductions. Preserve behavior and report evidence in maintainability or reduction mode.

1. Maintainability: over-abstraction, generic naming, noisy comments, invented APIs or configuration, stale idioms, dependency creep, and weak tests.
2. Safe reduction: dead or superseded code, orphan files, exact clones, redundant wrappers, inert defensive scaffolding, and comment walls.

Smaller code is not automatically better. A finding needs a concrete maintenance or correctness cost, an invariant, and evidence that the proposed change preserves contracts.

When to use

• Review code or a PR for unnecessary complexity, AI-shaped code, grounded API use, and useful tests.
• Find behavior-preserving reductions before a cleanup change.
• Check a removal or refactor diff for lost behavior, fallbacks, or reachable entry points.

When NOT to use

• Find logic bugs, races, or regressions: use code-review.
• Find vulnerabilities or secrets: use security-audit.
• Rewrite prose for voice: use anti-ai-prose.
• Run a repository-wide multi-lens audit: use repo-audit.
• Implement a cleanup: use the relevant language or framework skill.

Workflow

1. Scope: prefer the named path or diff; otherwise inspect uncommitted changes, then the current branch against its confirmed integration base. Record generated, vendored, and unreviewed areas.
2. Establish context: read instructions, manifests, runtime versions, public exports, registries, route/CLI/plugin discovery, and existing validation. For maintainability mode, load references/maintainability-patterns.md and each relevant language or infrastructure reference; for reduction mode, load references/patterns.md and references/reduction-patterns.md. Load references/research-sources.md only when citations help.
3. Make a maintainability pass: inspect scripts and configuration before running any baseline tooling. Run only configured, non-mutating check commands; never use --fix, --write, apply, or an unknown script. Then inspect comments, naming, types, wrappers, error handling, dependencies, API/config claims, and tests (including test bloat, see Rules). Verify suspicious APIs with local types, schemas, lockfiles, --help, or primary documentation before calling them invented.
4. Make a safe-reduction pass: search for dead and superseded code, leftovers, clones, one-literal-per-function copies, redundant parsers, thin wrappers, and inert catches. Read each candidate, a caller, and relevant tests.
5. Prove or defer: search with rg -n (use grep -rn when command -v rg fails). A deletion needs no-reference proof that rules out public APIs, reflection, dynamic dispatch, DI, serialization, route/CLI/plugin registration, conditional builds, and test discovery. Preserve boundary guards, recoveries, retries, cleanup, observability, compatibility, and intentional provider divergence.
6. Classify: use Do now only for mechanically proven, behavior-preserving reductions; Do with tests when focused validation is missing; Defer for broad, hot-path, or uncertain work; Leave alone when the current shape carries a contract. Also classify maintainability findings as Noise, Lies, or Soul and as Fix, Consider, or Fine (defined in references/maintainability-patterns.md); project conventions and framework idioms override generic style rules.
7. Report: write an audit deliverable using references/report-templates.md. Group repeated examples into one finding and include location, evidence, invariant, proposed shape, tradeoff, and validation needed.