improve-architecture

Run the skill and it uses subagents to explore the codebase, flagging modules whose interfaces are nearly as complex as their implementations. It presents 3-5 candidate clusters with the files involved, why they are coupled, and the friction they create.

A deep module has a small interface hiding a large implementation, so callers get significant functionality through minimal surface area. Shallow modules are the opposite: their interface complexity rivals their implementation, adding coupling without hiding complexity.

After you pick a candidate cluster, it spawns multiple subagents in parallel, each producing a radically different interface design. It then presents all options, recommends the strongest, and can propose a hybrid combining elements from different designs.

Yes. Once you accept a design, it creates a GitHub issue as a refactor RFC describing the current state, the proposed interface, the migration path, and the affected files, ready for team review.

Avoid it when modules are shallow because they are genuinely simple utilities, or when a refactor would destabilize code under active change. The skill is best suited for coupled clusters where integration risk concentrates at module seams.