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.

When the user has already selected a candidate or concrete target change, inspect that target and proceed directly to exploring it. Do not produce another candidate menu or ask them to select it again. A named subsystem may instead limit discovery when the user is still asking which change would help.

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

• Consult codebase-design for deep-module principles, caller contracts, and seam justification. Use its architectural distinctions alongside established product and repository vocabulary. Evaluate what an interface hides and what callers gain; adapter count alone does not justify or rule out a seam.
• The project's glossary gives names to good seams; its ADRs record decisions this command should not re-litigate. Follow the existing documentation locations rather than assuming CONTEXT.md and docs/adr/.

Process

1. Explore

Scope before you scan: YAGNI. Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. 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, use recent commit history (git log --oneline) to select an initial area where repeated change suggests maintenance cost. Broaden that area only when the evidence or requested coverage warrants it.