name: improve-architecture description: Audit an area of the codebase and propose the smallest structural moves that improve it - untangle boundaries, kill duplication, fix seams, break cycles. Produces a prioritized plan and decision records, not a rewrite. Use when a codebase feels tangled, hard to change, or is becoming a ball of mud, or when asked to improve or refactor architecture. user-invocable: true
improve-architecture
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).