refactor-advisor

refactor-advisor

Surface architectural friction and propose deepening — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability. Markdown only, no agents, read-then-propose.

This is the home for /diagnose's Phase-6 finding ("no good test seam = architecture preventing lockdown") and /tdd's "shallow module → deepen" candidates.

Vocabulary (use these exactly — full definitions → ${CLAUDE_SKILL_DIR}/references/deepening.md)

• Module — anything with an interface + an implementation (function, class, package, slice).
• Interface — everything a caller must know: types, invariants, ordering, error modes, config. Not just the signature.
• Depth — leverage at the interface: lots of behaviour behind a small interface. Deep = high leverage; shallow = interface nearly as complex as the implementation.
• Seam — where the interface lives; a place to alter behaviour without editing in place. (Say seam, not "boundary".)
• Adapter — a concrete thing satisfying an interface at a seam. Leverage = what callers get; locality = what maintainers get.

Three rules that do most of the work:

• Deletion test — imagine deleting the module. Complexity vanishes → it was a pass-through. Complexity reappears across N callers → it earned its keep. (The simplicity ladder's delete > add — favour removing over adding.)
• The interface is the test surface — callers and tests cross the same seam. Needing to test past the interface = wrong shape.
• One adapter = a hypothetical seam; two = a real one. Don't add a port unless something actually varies across it.

Process

1. Explore

Scope before you scan — YAGNI. Deepening pays off by making future changes easier, so it earns nothing in code that never changes. If the user named a direction, take it; otherwise walk back a good stretch of git log --oneline and let the files that keep reappearing pull your attention first. Scattered history with no hot spot → widen the net.