code-simplifier

name	code-simplifier
description	Simplifies code by deleting dead code, merging duplication, reducing unnecessary abstractions, and preserving behavior. Use when cleaning messy, legacy, duplicated, over-engineered, MVP, prototype, or hard-to-maintain code.

Code Simplifier

Use this skill to make code smaller, clearer, easier to review, and easier to verify. This is a deletion-first refactoring workflow, not a redesign workflow.

Operating Principle

Decide in this order:

1. Can it be deleted?
2. Can it be merged with existing code?
3. Can it be simplified in place?
4. Only then, is new code necessary?

Prefer fewer files, functions, branches, wrappers, dependencies, config points, concepts, and special cases. Do not make code look more advanced; make it easier to understand and prove correct.

Use For

• Removing unused code, imports, variables, files, helpers, dependencies, or config.
• Merging duplicated logic with the same behavior.
• Collapsing pointless wrappers, pass-through functions, adapters, factories, or managers.
• Simplifying long, nested, branching, or overly defensive functions.
• Cleaning historical patches, MVP code, prototype scaffolding, and abandoned experiments.

Do not use this skill for feature work, broad architecture changes, framework migrations, behavior redesigns, large rewrites, or performance/security/auth/payment/data-migration work unless the user explicitly asks.

Hard Rules

• Preserve behavior unless fixing a confirmed bug.
• Keep each round focused on one small, reviewable goal.
• Edit existing code before adding files.
• Merge duplication before creating abstractions.
• Prefer direct control flow over hidden indirection.
• Verify before and after changes when practical.
• Separate pre-existing failures from newly introduced failures.
• Never delete logic, tests, public APIs, compatibility paths, or config that you do not understand.
• Never move complexity somewhere else and call it simplification.
• Never claim the change is safe without evidence.

Risk Guide

Low-risk after reference checks:

• Unused imports, local variables, comments, empty files, unreachable code.
• Unreferenced internal helpers.
• Duplicate helpers with identical behavior.
• Demo or prototype code unused by docs, tests, scripts, CI, or package entries.
• Dependencies unused across imports, scripts, config, and lockfiles.

Medium-risk only when the affected path is understood and verifiable:

• Merging similar functions.
• Simplifying branches or error handling.
• Collapsing wrappers.
• Consolidating config reads.
• Removing debug output.
• Reducing nesting in one function.

High-risk: stop and ask before changing:

• API routes, CLI entry points, public SDK/library APIs.
• Database migrations or persisted data handling.
• Auth, permissions, payment, security, audit, telemetry, logging, metrics, tracing, or monitoring.
• Deployment, CI, Docker, environment config, scheduled jobs, webhooks.
• Dynamic imports, plugin registries, auto-discovery, legacy compatibility logic.

When unsure, treat the change as high-risk.

Workflow

1. Inspect first. Identify entry points, tests, scripts, dynamic loading, public surfaces, duplicated logic, dead code, wrappers, and verification commands.
2. Establish a baseline. Run the strongest practical checks before editing: tests, lint, typecheck, build, syntax/import checks, startup command, or key CLI/API flow. Record existing failures.
3. Pick one small goal. Examples: remove unused imports, delete one unreferenced helper, merge one duplicated parser, simplify one complex function, collapse one wrapper layer, remove one unused dependency.
4. Check references before deletion. Search direct imports, string references, routes, config keys, scripts, docs, tests, fixtures, CI, Docker, package entries, plugin registries, dynamic imports, and auto-discovery paths.
5. Apply the smallest behavior-preserving change that reduces code or complexity. New code is allowed only when it removes more complexity than it adds.
6. Verify again with the same or stronger checks. Compare with the baseline and fix any newly introduced failure.

Stop Conditions

Stop and report instead of continuing when:

• The change requires behavior or API changes.
• The affected path cannot be verified.
• Reference checks are inconclusive.
• The code is dynamically loaded or externally exposed.
• The diff grows beyond the selected small goal.
• Tests fail in a new way.
• Business rules are unclear.
• The work becomes feature development or architecture redesign.

Report Format

Use a short evidence-based summary:

## Simplification Goal
[One small goal]

## Baseline
- Checks run:
- Pre-existing failures:

## Changes
- Deleted:
- Merged:
- Simplified:
- Intentionally not touched:

## Result
- Files changed:
- Net complexity reduction:
- Checks after change:
- Remaining risk:

Success Criteria

A good simplification reduces code size or obvious complexity, preserves behavior, avoids new dependencies, keeps the diff easy to review, and includes verification results.

A bad simplification adds abstractions, expands file structure, changes behavior silently, removes tests to pass checks, or only formats/renames code without reducing complexity.