Invest in the shape of the system a little at a time rather than paying for a rewrite later. This skill diagnoses and proposes; it does not rewrite on its own.
Method
- Map first. Get the current shape before judging it - entry points,
modules, data flow, who calls whom. Reuse
module-mapfor the one-screen view; do not skip to opinions. - Find the strain. Look for the load-bearing problems, not style nits:
- God modules that everything imports and nothing can change safely.
- Leaky boundaries - a module reaching into another's internals instead of its surface.
- Duplicated logic that drifts (the same rule implemented three ways).
- Wrong seams - the code is split where it does not bend and fused where it does.
- Cyclic dependencies.
- A shape that fights the domain (see
domain-modeling- boundaries in code should track boundaries in the language).
- Propose the smallest move. For each problem, the least change that relieves it: extract a boundary, collapse a duplicate, invert a dependency, move a seam. Prefer a sequence of safe steps over one big cut.
- Rank by leverage. Order the moves by pain relieved over effort. Say which
are safe now and which need a test net first (pair with
tdd). - Record the big calls. For a structural change a future reader would
question, write a decision record in
docs/decisions/NNNN-slug.md: context, choice, alternatives rejected, why.
Guardrails
- Diagnose, do not rewrite. The deliverable is a plan the user approves before any code moves.
- No churn for taste. A move must relieve a named strain; "cleaner" is not a reason.
- Three similar lines beat a premature abstraction - do not trade duplication for indirection unless the duplication actually drifts.
- Keep behavior fixed. Structural moves are refactors; land them behind green tests.
Output
A prioritized list: each item is the problem, the smallest move, the risk, and whether it needs a test net first. Plus decision records for the big moves. No code changes until the user picks what to do.