Refactor for maintainability

Measure where the debt actually is and map real dependencies before pinning behavior and refactoring.

Also usessuperpowers

Refactoring's defining constraint is that behavior must not change — which makes the before-picture and the after-proof more important than the edit itself. Superpowers' test-driven-development pins behavior first; codebase-consistency:equivalence-verifier re-checks it afterward, genuinely post-hoc.

Start here

One prompt to start

I want to refactor this for maintainability -- measure where the complexity and architecture debt actually is before touching anything, pin the current behavior down with tests first, and once the refactor is done, check for contract drift and have an independent pass confirm the module behaves identically to before, from the diff rather than from my own account of what changed.

Needsself-assess, superpowers, confab, codebase-consistency

Beats

Run these in order. Each prompt is copy-pasteable straight into Claude Code.

1. self-assess:self-assess-complexity-score

   Refactoring by intuition targets the code that is annoying rather than the code that is costly.

   Run this beat on its own

   measure complexity and size per module so we refactor where the debt actually is

2. self-assess:self-assess-arch-health

   God-modules, cycles, and layering violations are structural findings; a refactor that ignores them relocates the problem.

   Run this beat on its own

   check this repo's architecture health — god modules, cycles, layering violations, with evidence

3. superpowers:test-driven-developmentalso in 3 other recipes

   • Root-cause a bugfix from a tracked issue
   • Build a new feature in an existing codebase
   • Collapse duplication hand-synced across N sites

   Characterization tests written after the refactor characterize the refactor.

4. confab:confab-contract-driftalso in 3 other recipes

   • Collapse duplication hand-synced across N sites
   • Migrate a return shape or type representation
   • Whole-branch review without re-trusting the branch's own self-assessment

   Its own description scopes it to checking "for contract drift after a refactor."

   Run this beat on its own

   check for contract drift after this refactor — signatures, type hints, docstring params, schemas

5. codebase-consistency:equivalence-verifier

   Genuinely post-hoc: it re-checks that the module behaves identically to before and that its docs and comments still match, from the diff rather than from the refactorer's own report.

Worked example

Grounded in — why this beat order is trustworthy

`tools/plugin-serializer/` holds four scripts — `build_inventory.py`, `contract_diff.py`, `extract_behavior.py`, `generate_plugin.py` — whose shared assumptions about plugin shape make it a real candidate for the measure-then-map-then-pin sequence above.

Do / Don't

• ✓Measure complexity and size per module before refactoring -- targeting by intuition hits the code that's annoying, not the code that's costly.
• ✓Check for god-modules, cycles, and layering violations before refactoring -- a refactor that ignores them relocates the problem instead of fixing it.
• ✓Write characterization tests before the refactor, not after -- tests written after a refactor only characterize the refactor.
• ✓Have equivalence checked post-hoc, from the diff itself, rather than trusting the refactorer's own report of what changed.

• ×Don't refactor by intuition -- it targets the annoying code, not the costly code.
• ×Don't ignore god-modules, cycles, or layering violations found in the architecture check -- a refactor around them just relocates the problem.
• ×Don't write the characterization tests after the refactor -- by then they characterize the refactor, not the original behavior.
• ×Don't rely on your own report that behavior is unchanged -- verify it independently from the diff and the module's own tests.