git:20260920.ac01853 to git:20260920.ebf9a3d

---

name: code-simplification

description: "Review code for dead code, duplication, overengineering, invented APIs, and weak tests. Report safe reductions; no edits."

license: MIT

compatibility: "None - works on any codebase"

metadata:

source: iuliandita/skills

date_added: "2026-09-20"

effort: medium

argument_hint: "[scope-or-diff]"

---

# 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. 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:** 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.

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.

## AI Self-Check

- [ ] Every API, CLI flag, schema key, and version-sensitive replacement is grounded in the target project.

- [ ] Every safe-reduction finding states its preserved behavior and no-reference or behavior-specific evidence.

- [ ] Tests are judged by behavior and acceptance criteria, not mock volume or coverage alone.

- [ ] Framework conventions, public contracts, intentional duplication, and separate trust boundaries were checked.

- [ ] Findings are honest about priority and use one representative example for repeated patterns.

- [ ] Cross-cutting hygiene is applied from `references/agent-hygiene.md`.

## References

- `references/maintainability-patterns.md` - quality, grounding, test, and language prompts.

- `references/typescript.md`, `python.md`, `shell.md`, `rust.md`, `docker.md`, and `iac.md` - detailed language and infrastructure prompts.

- `references/patterns.md` - detailed safe-reduction classification and no-reference guidance.

- `references/research-sources.md` - optional source context when citations help.

- `references/reduction-patterns.md` - dead-code and behavior-preserving reduction proofs.

- `references/report-templates.md` - audit and removal-review deliverables.

- `references/output-contract.md` - required reporting format.

## Output Contract

Use `references/output-contract.md`.

- **Skill name:** CODE-SIMPLIFICATION

- **Deliverable:** `docs/local/audits/code-simplification/<YYYY-MM-DD>-<slug>.md`

- **Mode:** always-on for audits and reviews; answer a factual question without a deliverable.

- **Priority:** P0-P3 and info. A simplification finding is normally P2 or P3; route correctness and security impact to its owning audit.