What problem does it solve?
This skill addresses the friction of maintaining codebases with scattered shallow modules, where logic is duplicated across many small wrappers, changes require editing multiple locations, and testing is fragmented across low-value unit tests instead of targeting core behavior.
Core Features & Use Cases
- Shallow module detection: Automatically identifies modules where interface complexity nearly matches implementation complexity, indicating poor leverage.
- Deepening opportunity surfacing: Proposes concrete refactors to consolidate scattered logic into deep modules with small, high-leverage interfaces.
- Visual architecture reports: Generates self-contained HTML reports with before/after diagrams illustrating module shallowness and proposed deepening changes.
- Interface design exploration: Supports iterative design of alternative interfaces for selected deepening candidates using a parallel sub-agent pattern.
- Use case: For a codebase with order processing logic split across 5 small, tightly-coupled modules, this skill surfaces the opportunity to collapse them into a single deep order module with one testable interface, eliminating duplicate validation logic and reducing test maintenance overhead.
Quick Start
Use the improve-codebase-architecture skill to analyze your codebase and generate a visual report of architecture improvement opportunities.
