# Cleaner

> Use when AI-generated code has bloated the repo: oversized files or classes, dead or unused code (functions, imports, variables, types, whole files), or duplicated blocks that need merging. Behavior-preserving cleanup only. Run when the user says "clean up this code", "remove dead code", "split this file", "this file is too big", "deduplicate", or "refactor without changing behavior". Not for new features, bug fixes, performance work, or over-engineering review.

- Skill: `swellshinider/cleaner` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add swellshinider/cleaner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swellshinider/cleaner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Swellshinider (https://skillmd.com/u/swellshinider)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/swellshinider/cleaner

---


# Cleaner

Behavior-preserving cleanup. Smaller files, no dead code, no duplication, same
behavior. The test suite ends green and the public surface is unchanged. If a
change would alter behavior, do not make it.

## The Contract (non-negotiable)

1. **Tests first.** Run the project's tests before touching anything. Record
   green or red. If there is no test suite, say so and ask before proceeding.
2. **One change at a time.** Apply one logical edit, re-run the tests, then
   commit or revert. On the first failure you did not cause, stop and revert.
3. **Public surface frozen.** Exported names, function signatures, types, and
   module paths stay identical. Internal moves only.
4. **No dynamic guesses.** Never delete code that may be reached by reflection,
   string dispatch, `eval`, dependency injection, or `__all__`-gated exports.
   When unsure, keep it and flag it for the human.
5. **Every change gets a diff and a one-line reason.** Group changes into a
   reviewable set; nothing lands silently.

## How it works

Assess, propose, execute. Use the detection scripts to find candidates, rank
them by safety, then apply one at a time with verification.

- **Assess.** Run `scripts/find_oversized.py`, `find_unused.py`, and
  `find_duplicates.py`, each with `--json`. Build a findings list.
- **Propose.** Rank by blast radius: pure-internal dead code first, then
  duplication, then file or class splits last. State the order out loud.
- **Execute.** Apply one change, run the tests, commit or revert, repeat.

## Operations

### Dead code

Remove unused functions, imports, variables, types, and whole files. Confirm
zero references with a whole-repo grep, including inside strings and comments
(dynamic dispatch hides there). See `references/cleanup-safety.md` for the
per-language patterns that defeat a naive grep.

### Split oversized files or classes

When a file or class is too large, extract cohesive units into new modules.
Re-exports keep the public surface stable: the old path re-exports from the new
location so callers and imports do not change. Run the tests after every move.

### Deduplicate

When two or more blocks do the same thing, merge them into one shared helper.
The helper keeps the most general signature that preserves every existing call
site. Replace each duplicate with a call to the helper. Run the tests.

## Red flags, STOP

You are about to violate the contract if any of these is true. Stop, do not
proceed.

- The thing has no static references, but the codebase uses reflection, DI, or
  string dispatch. **Keep it, flag it.**
- Tests are red before you started and you moved on anyway. **Stop, report.**
- "It's obviously unused" without a whole-repo grep. **Stop, grep first.**
- You would touch an exported name or signature to make a split fit. **Stop,
  replan around a re-export.**
- You are about to skip the post-change test run. **Stop, run it.**

## Verification

Done means: tests green before and after, `git diff` scoped to internals only,
public names unchanged, and a one-line behavior-identical summary per change.
Run the type checker or linter if the project has one.

## Tools

- `references/cleanup-safety.md` - dynamic-reference and public-API detection
  per language, test and rollback patterns.
- `scripts/find_oversized.py` - files and units over a line threshold.
- `scripts/find_unused.py` - definitions with no static references.
- `scripts/find_duplicates.py` - repeated or near-repeated code blocks.

## Boundaries

Out of scope. Route these elsewhere:

- New features and bug fixes. Behavior must change, the cleaner does not.
- Structural reorganization across files and directories. Use the manager skill.
- Performance work.
- Over-engineering review (ponytail's lane).
- Formatting and style. Use the project's linter or formatter.