What problem does it solve?
This Skill solves the problem of architectural friction in codebases caused by shallow modules, tight coupling, and poorly defined seams that make maintenance difficult, testing unreliable, and AI-assisted coding error-prone.
Core Features & Use Cases
- Deepening Opportunity Identification: Scans the codebase to find shallow modules where the interface is nearly as complex as the implementation, and assesses deepening feasibility based on dependency categories (in-process, local-substitutable, ports & adapters, external mocks).
- Domain-Aligned Recommendations: Uses project-specific domain language from CONTEXT.md and respects existing architectural decision records (ADRs) to avoid re-litigating settled choices unless real friction warrants revisiting them.
- Visual HTML Reports: Generates self-contained, interactive reports with before/after diagrams (call graphs, mass diagrams, cross-sections) of proposed refactors, using Tailwind and Mermaid via CDN for clear, editorial visuals.
- Use Case: For a growing codebase with dozens of small, tightly-coupled utility modules, use this Skill to identify which modules can be consolidated into deep, testable units with clear interfaces, reducing code duplication and improving test coverage.
Quick Start
Use the improve-codebase-architecture skill to analyze your project's codebase and generate a visual report of refactoring opportunities to deepen shallow modules and improve testability.
