improve-codebase-architecture

Run this Skill and it launches an Explore subagent that walks the code looking for modules whose interface is nearly as complex as their implementation. It applies the deletion test: if deleting a module would concentrate complexity rather than move it, that module is a deepening candidate.

A deep module has a small interface hiding a substantial implementation, while a shallow module's interface costs almost as much as it hides. The Skill uses this vocabulary from the companion codebase-design skill and flags shallow modules as refactoring candidates.

The report is a single self-contained HTML file written to the OS temp directory, styled with Tailwind and using Mermaid plus hand-built SVG for before/after diagrams. Each candidate card shows files, problem, solution, benefits, and a Strong, Worth exploring, or Speculative badge.

The HTML report is written to the OS temp directory, not the repo, so nothing lands in your project. During the grilling phase it may update CONTEXT.md with new domain terms or offer to record an ADR, but only with your agreement.

The Skill runs a grilling loop that walks the design tree with you: constraints, dependencies, the deepened module's shape, and what tests survive. It can also explore alternative interfaces using a design-it-twice parallel sub-agent pattern.

Skip it when an existing ADR already forbids the refactor and the friction is not severe enough to reopen that decision. The Skill deliberately suppresses theoretical refactors that contradict recorded architectural decisions unless the pain is real.