Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

This skill is built on a shared design vocabulary and informed by the project's domain model:

• The codebase-design skill holds the architecture vocabulary — module, interface, depth, seam, adapter, leverage, locality — and its principles: the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real". Read it before you scan, and use those terms exactly in every suggestion.
• CONTEXT.md gives names to good seams; ADRs in docs/adr/ record decisions this skill should not re-litigate. Both formats are documented in the grill-me skill, if it's installed alongside: CONTEXT-FORMAT.md, ADR-FORMAT.md.

Process

1. Explore

Scope before you scan. Deepening a module pays off by making future changes to it easier, so weight the parts of the codebase that keep moving. Decide where to look before you look:

• If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below.
• Otherwise walk back a good stretch of git log --oneline for the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.

Read the existing documentation for that area first: