python-refactor-auditlisted

Use when an existing Python module has grown and the question is how to restructure it safely, not what to write — auditing a file nobody has reviewed as a whole, planning the change as a sequence of small commits each verified on its own, deciding which tests may be edited to follow a rename and which must not change at a character, proving an edited test still fails when the production change is reverted, finding a second oracle when the suite cannot see the change (a field's type changing under a name every caller already uses), measuring the shape you are trying to remove before and after so a large diff that moves nothing is caught, and deciding when not to restructure at all. For what a given piece of Python should look like — data modeling, dates, settings, modularity and singleton defaults — see the Python conventions skill; for what a test should cover, the Python testing skill.
TheodoreAD/agent-skills · ★ 0 · Code & Development · score 75

Install: claude install-skill TheodoreAD/agent-skills

# Auditing and restructuring a Python module that grew A procedure for the pass nothing else does: a module built incrementally, never reviewed as a whole, where the problem is not any single line but a shape repeated across the file. Every diff-scoped reviewer — a code-review command, a simplifier agent, a PR bot — is scoped to recent changes by design, and whole-module state threading is precisely what no diff contains. This skill is about **how the pass is run**, which matters more than the target shape. What the resulting code should look like is `python-conventions`; what a test should cover is `python-testing-conventions`. The loop, the oracle rules and the stopping rule below are language-neutral; the examples are Python. The worked example every rule here comes from is in [`references/pilot.md`](references/pilot.md) — a 3,476-line single-file script restructured in nine commits on 2026-09-01, with its before/after counts, the two counts that did not reproduce, and the things that went wrong. [`references/prior-art.md`](references/prior-art.md) is what was surveyed and what was deliberately not taken. ## What this skill reads, runs and writes - **Reads**: the module you point `scripts/count_shapes.py` and `scripts/find_mutations.py` at. - **Runs**: nothing. - **Writes**: nothing. The commits the loop below produces are yours, in your repo, one at a time. - **Network**: none. ## First decide whether to restructure at all **Four stopping conditions. Any one of the