remove-deadcode-py

Remove Dead Code (Python)

Delete unused code from Python projects. Detection relies on tools, conviction relies on evidence, deletion goes in small batches, and clearing everything in one pass is not the goal.

This skill is the on-demand entry for repo-wide cleanup and does not do task close-out (close-out goes through cleanup). The method is inspired by code-yeongyu/oh-my-openagent's remove-deadcode (no text copied); tool behavior defers to the official vulture/Ruff/deptry docs. Repo-wide scanning for non-Python ecosystems is out of scope for this skill: use knip for JS/TS, go tool deadcode for Go, and cargo-machete for Rust.

Workflow

1. Pin down entry points (mark off the undeletable zone first): [project.scripts] and entry_points in pyproject.toml/setup.cfg, __main__.py, app.py/run.py/manage.py, conftest.py, Django models/admin/urls/migrations, Celery tasks, plugin registration points. Entry points and framework auto-discovery surfaces = undeletable.
2. Fast lane: ruff check --select F401,F841 for unused imports/variables; with --fix, accept only safe fixes — F401 in __init__.py is re-export semantics (Ruff flags it as unsafe); do not delete by hand before confirming __all__. If deptry is installed, also run deptry . for unused dependencies.
3. Main scan: vulture <src> --min-confidence 60. 60% (attributes/classes/functions) is only a lead; 90% (imports) can proceed to conviction; 100% (unreachable code) is mostly trustworthy but still goes through step 4.
4. Conviction (triple evidence; missing any one downgrades to needs-review):
   • Zero references in a repo-wide grep — the scope covers source, strings, comments, config, docs, CI/workflows, Makefile/Dockerfile;
   • git log --follow <file> provenance: added for an abandoned feature, or long untouched, strengthens the call; recently active ones get downgraded;
   • Optional corroboration: never executed in test coverage (coverage report) ≠ dead code; it serves only as a bonus.
5. Guard list (a hit means keep, no matter what the tool says):
   • Dynamic references reachable within the range of getattr / globals() / eval / exec / __import__ / importlib;
   • Registration decorators: @app.route, @router.*, @cli.command, @click.*, @pytest.fixture, @celery.task and custom registration decorators (grep the decorator definition site to confirm the registration mechanism);
   • Dunder methods, abstract-method/Protocol implementations, operator overloads, dataclass/Pydantic fields;
   • re-exports and __all__ in __init__.py;
   • Referenced by test files = a legitimate consumer;
   • Packaging-config references: include/packages in pyproject.toml, setup.cfg, MANIFEST.in.
6. Batched atomic deletion: one module or one group of related symbols per batch; after each deletion run the project's narrowest tests + typecheck (if configured); commit only when green (the message states the evidence basis); on failure, git checkout -- <files> rolls back this batch, then shrink the batch size.
7. Cascade rescan: after each finished batch, rerun vulture — deletions expose new dead code. Produce the report once all batches are done.