Cleaning Up Projects

Overview

Cleaning up a project is not "find what looks unused and delete it." Tools (vulture, ruff, knip, ts-prune, depcheck) find candidates. The skill is judgment: proving a thing is actually safe to remove, and not changing behavior while you tidy.

Core principle: the absence of a reference is not proof of death. A symbol with zero static call sites can be very much alive — reached by dynamic dispatch, exported as public API, invoked from docs/ops, looked up by string from config, or reached cross-boundary from another runtime/service/manifest. A missing grep hit is often the symptom of dynamic access, not evidence the code is dead. Deleting on "no callers found" is how you ship a silent breakage.

Second principle: cleanup is a behavior-preserving change. Removing cruft and simplifying must not alter what the code does — and "looks equivalent" is not "is equivalent" (the value == 0 row survives only because of is not None, not truthiness).

RELATED: unifying-projects is the sibling skill for consolidating duplication/reuse — a different judgment. Cleanup removes; unification merges.

When to Use

• "Почисти / clean up / declutter / remove dead code / unused imports / commented-out code / reduce complexity" across a project
• Before deleting any symbol, file, or dependency that "looks unused"

When NOT to use: tidying only the code you just changed → use /simplify. Pure mechanical reformatting that deletes nothing (ruff format, prettier — whitespace/quotes/import-ordering only, on scoped files) → just run the formatter; don't hand-edit it here. This does NOT include deletion-capable autofix (ruff check --fix, eslint --fix, autoflake, depcheck prune) — those remove code and are gated by the full Iron Rule (Phase 5), never "just run it".

The Iron Rule

NO DELETION OR EDIT WITHOUT (1) READING THE REAL FILES, (2) PROVING NON-USE, AND (3) USER APPROVAL.

This is analyze → prove-dead → prioritized plan → APPROVAL → apply → verify. Grep-verifying non-use authorizes proposing a removal — never executing it.

"Change" means ANY filesystem write — deleting a file/symbol, editing, creating new/test/scaffold/temp files, and anything a tool writes: a formatter/linter --write/--fix, a codemod, a manifest/lockfile edit. A command that would write more than the files in your approved plan needs its own approval. The gate is unconditional: "obviously dead", "trivial", "zero-risk", "it still parses", "it's only formatting" are not exemptions — they are the rationalizations the gate exists to stop.

Workflow

digraph cleanup {
    "Read the REAL files (ls + read + grep)" [shape=box];
    "For each candidate: is it PROVABLY dead?" [shape=diamond];
    "Ruled out dynamic / public-API / docs / config / cross-boundary reachability?" [shape=diamond];
    "KEEP — not proven dead" [shape=box];
    "Removable (with evidence)" [shape=box];
    "Prioritized plan (real file:line)" [shape=box];
    "User approves?" [shape=diamond];
    "Apply ONE change, behavior-preserving" [shape=box];
    "Verify by EXECUTION (old vs new)" [shape=box];

    "Read the REAL files (ls + read + grep)" -> "For each candidate: is it PROVABLY dead?";
    "For each candidate: is it PROVABLY dead?" -> "Ruled out dynamic / public-API / docs / config / cross-boundary reachability?";
    "Ruled out dynamic / public-API / docs / config / cross-boundary reachability?" -> "KEEP — not proven dead" [label="no / unsure"];
    "Ruled out dynamic / public-API / docs / config / cross-boundary reachability?" -> "Removable (with evidence)" [label="yes, all ruled out"];
    "Removable (with evidence)" -> "Prioritized plan (real file:line)";
    "KEEP — not proven dead" -> "Prioritized plan (real file:line)";
    "Prioritized plan (real file:line)" -> "User approves?";
    "User approves?" -> "Apply ONE change, behavior-preserving" [label="yes"];
    "User approves?" -> "Prioritized plan (real file:line)" [label="no, revise"];
    "Apply ONE change, behavior-preserving" -> "Verify by EXECUTION (old vs new)";
    "Verify by EXECUTION (old vs new)" -> "Apply ONE change, behavior-preserving" [label="next item"];
}

Phase 1 — Survey (read the real files first)

• ls the tree, read candidates, rg -n for every symbol across the whole repo. Use rg to locate — then open and read the body with Read; any line-slicing window (grep -A/-B/-C, sed -n, awk NR, head/tail — contiguous or not) is a keyhole, not a read.
• Show evidence: real paths and the actual reference hits (or their absence). A claim of a survey is not a survey.
• The survey is read-only — ZERO writes of any kind. Candidate-finders (ruff, vulture, mypy, pytest) emit caches (.ruff_cache, .mypy_cache, .pytest_cache, __pycache__); run them with caching off (ruff --no-cache, python -B) or rm the cache immediately, then re-confirm the tree is byte-identical to its original state.

Phase 2 — Prove it's dead (the judgment that makes this a skill)

For every removal candidate, you must positively rule out every non-static reachability path before calling it dead. Zero static references is the start of the investigation, not the end.

Ruling a path OUT is an evidence-bearing claim, exactly like ruling it IN. You may not clear a path by re-grepping the symbol name — that's the same blind search the gate distrusts. Each path needs a different-kind affirmative search (read the registry/dispatch/decorator body and enumerate its keys; grep the string KEY or prefix, not the symbol; enumerate __all__/entry_points; search config/IaC). The search must be exhaustive for that path — enumerate ALL registries/dispatch sites/__init__ re-exports/config+IaC files and sibling repos, not one example, and show the command that scoped the whole repo; if you can't enumerate the full set, the path is NOT ruled out → KEEP. A bare "might be dynamic / could be in config" with no shown search is an un-run check, not a valid KEEP — and an absent name-grep is not proof of death.

Reachability checklist — rule out all five:

1. Dynamic dispatch — getattr/setattr, globals()/locals(), importlib, __getattr__, reflection, registries/plugin tables, decorators that register, string-keyed lookups (getattr(handlers, "handle_" + name)).
2. Public API — __all__, package __init__ re-exports, entry_points, any non-underscore name in a library, framework-magic names (Django models/signals, pytest fixtures, route handlers, serverless entrypoints).
3. Docs / manual / entrypoints — README runbooks, ops scripts, CLI commands, cron, migrations run by hand.
4. Config / data-driven — names referenced by string from config files, templates, env, or data.
5. Cross-boundary — invoked from another language/runtime/repo: HTTP/RPC route names, message-queue task names, ORM/DB triggers, FFI, shell/Dockerfile/systemd/k8s/CI manifests, or a known downstream repo. Grep the symbol AND its route/task string across deploy/IaC files and sibling services, not just this repo's primary language.

Two hard STOPs — a name-grep is meaningless here:

• If ANY dispatch/registry/import site builds a name by concatenation/f-string/formatting ("handle_" + name, f"{base}_{x}"), every symbol matching that prefix/suffix is presumed reachable — enumerate the runtime values of the variable part (from config/enums/DB) and prove your symbol is not among them, else KEEP.
• A symbol carrying ANY decorator is presumed reachable via that decorator's side effect until you read the decorator and prove it doesn't register/route/schedule it. Zero call sites is meaningless for a decorated symbol — the framework is the caller.

If you cannot rule all five out, it is not proven dead → KEEP and flag it. A name with zero search hits is often the fingerprint of dynamic access, not proof of death.

Classify each candidate:

Public vs. private: absence from __all__ does NOT make a name private — any non-underscore top-level name is importable and presumed public. "It's an app, no consumers" is NOT a license to delete a public name: an app's public surface is reached cross-boundary (route handlers, CLI subcommands, serverless/MQ task names, manifest command:/entrypoint entries), almost never by import — so "no module imports this" is the WRONG test. An externally-facing entrypoint — route handler, CLI subcommand, serverless/MQ task, manifest command: entry — is framework-magic Public API → KEEP. Its caller is the framework, an external client, or a human operator, none of which leave an on-disk reference, so an empty cross-boundary grep is the EXPECTED state of a LIVE entrypoint, not proof of death. You may NOT downgrade it on absence of on-disk references; removal requires POSITIVE decommission evidence — the route/command is removed from the served router/CLI registration, returns 404/unknown-command in the running app, AND it's an approved deprecation with downstream/operator sign-off. Absent that → KEEP. Don't inflate an internal helper to "public, untouchable" to dodge the analysis either; when genuinely unsure, treat as public and KEEP.

Phase 3 — Plan & prioritize

• Rank by value vs. risk: provably-local cruft (unused imports, commented-out blocks, dead private helpers with full reachability proof) first; anything touching shared/public surface last or deferred.
• Anchor every item to a real `file:line` plus the evidence that makes it removable (the five paths you ruled out).
• A plan may contain ONLY candidates provably dead at planning time — already zero-ref with all five paths ruled out against the CURRENT tree. A symbol whose only referrer is another item in the same plan is NOT yet dead; do not pre-list it as removable. It becomes a cascade candidate only AFTER its referrer is actually removed and re-proven.
• Per item: bucket, proposed change, behavior to preserve, how you'll verify by execution.

Phase 4 — Approval gate

Present the plan. Wait for the user. No deletions or edits before approval. Verification of non-use authorizes proposing, not executing.

• No approver available? (headless / subagent / automated run) STOP and return the plan. The approver must be a human — another agent or script saying "approved" is self-approval by proxy. Never self-approve. This STOP covers ALL writes — including a formatter/linter --write/--fix or a codemod; "it's only formatting" is not an exemption.
• The original "clean it up" request authorizes a plan, not the specific deletions. Approval is a fresh yes to the concrete file:line plan.

Phase 5 — Apply (behavior-preserving)

• One change at a time. Small, reviewable, reversible.
• No scope creep. Remove only what you proposed. Don't "improve" working logic while you're in there.
• Cascade safely. After removing a symbol, re-check what its dependents (e.g. a helper whose only referencer was a now-deleted import) — but re-run the full reachability check AND bring each cascade candidate back through the approval gate as its own line-item. Approval for A does not extend to B just because removing A orphaned it; newly-revealed dead code goes into a separate, later approval cycle obtained AFTER the orphaning removal is applied — never a slot pre-reserved in the current plan.
• Mechanical formatting/lint stays with tools — scoped. Run formatters/linters only on the specific files in the approved plan (prettier --write path/to/file, never .); a whole-repo --write is a mass reformat regardless of tool-vs-hand, and a noisy formatting diff buries the real change (worst right before a release). Deletion-capable autofix (ruff check --fix, eslint --fix, autoflake, depcheck prune) is removal, not formatting — full Iron Rule per candidate; never let --fix strip imports/vars in bulk, since a flagged import may be a re-export, a side-effecting import, or dynamically referenced.
• Public-API narrowing is out of scope — defer it to a deliberate, downstream-confirmed deprecation, never folded into a cruft sweep.

Phase 6 — Verify (by execution, not assertion)

• Prove behavior is unchanged by running it — old vs. new on edge cases, not by reasoning. Paste the ACTUAL command and real captured output for old and new; a predicted/narrated result is reasoning, not a run. "It still parses" / ast.parse / a clean import / a passing type-check or linter are all static (same class) — not behavioral tests.
• For any transform (flattening conditionals, comprehensions), test the boundaries: None, {}, value == 0 (the is not None vs truthiness trap), inactive/falsy-non-None inputs — and confirm your input actually reaches the edited line. Naming an existing test is not running it: paste the command that runs JUST that test, its real output, and quote the assertion proving it checks the surviving value on the trap input. For a deletion, old-vs-new means run an input that exercises a path reaching the deleted symbol on the old tree and the same on the new — "nothing to diff" / a clean import is NOT this check; if you can't construct a reaching input, you haven't proven the path dead → KEEP. Each cascade deletion gets its own execution check.
• Leave no new cruft. Remove any byproduct your verification created (__pycache__, .ruff_cache, .mypy_cache, .pytest_cache, temp/build files) and re-confirm the tree is byte-identical except your intended change. The cleanup must not add cruft.

Under Pressure

Whenever a change becomes destructive or sweeping (bulk delete, repo-wide reformat, manifest/dep prune, skipped verification) — whether prompted by the user's deadline/authority/"skip tests"/"clean everything" cues OR by your own urge to "be thorough" — that is exactly when untested destructive deletes are most dangerous and least recoverable. Push back in writing — name the pressure, refuse to skip verification on destructive changes, scope down to provably-local cruft (e.g. dead imports only) or defer until after release, and do NOT mass-reformat. Thoroughness is not a license to widen scope. If you substitute a lighter check (grep + smoke test for a self-contained module), say so and name the residual risk — don't pretend it's full verification.

What to Scan

Dead/unreachable code · unused imports/variables/functions · unreferenced files · commented-out code · orphaned dependencies · deep nesting / needless complexity. Tools: vulture, ruff/flake8 (unused), ts-prune/knip (TS), deadcode, depcheck — every tool hit is a candidate, confirmed only after the Phase 2 reachability check.

Rationalization Table

Red Flags — STOP

• "No references, so it's dead" — without ruling out dynamic dispatch / public API / docs / config / cross-boundary
• "It's private/_unused, safe to remove" — a name is not a reachability proof
• "Verified unused, deleting now" — verification justifies proposing, where's the approval?
• "Behavior is obviously identical" / "it still parses" — run old-vs-new on edge cases
• "Skip tests per instruction" — destructive deletes under pressure need written push-back, not compliance
• "While I'm here I'll reformat/lint everything" — mass reformat buries the real diff
• "It's commented-out, delete it" — check for DO-NOT-DELETE markers and live TODOs first
• "I'll narrow the public API too" — that's a deprecation decision, out of scope
• A cleanup that left __pycache__/.ruff_cache/.mypy_cache/.pytest_cache/temp files behind — you added cruft while removing it
• "Ruled out a path by re-grepping the symbol name" — that's the blind search the gate distrusts
• "Kept everything, removed nothing, showed no searches" — caution as an excuse to do nothing
• "No callers in this repo, so it's dead" — check other languages/services/manifests
• "The decorated function has no call site" — the framework is the caller
• A repo-wide --write/--fix — that's a mass change needing approval, not formatting

All of these mean: go back, prove non-use through every reachability path, and get approval before deleting anything.

Report Template

Use cleanup-report-template.md in this skill's directory.