Improve Codebase Architecture

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones.

Process

Read the project's domain glossary (CONTEXT.md) and any ADRs in the area you're touching first.

Walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:

Where does understanding one concept require bouncing between many small modules?
Where are modules shallow — interface nearly as complex as the implementation?
Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
Where do tightly-coupled modules leak across their seams?
Which parts of the codebase are untested, or hard to test through their current interface?

Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it?

Write a self-contained HTML file to the OS temp directory. For each candidate, render a card with:

Files — which files/modules are involved
Problem — why the current architecture is causing friction
Solution — plain English description of what would change
Benefits — explained in terms of locality and leverage
Before / After diagram — side-by-side illustrating the shallowness and the deepening
Recommendation strength — one of Strong, Worth exploring, Speculative

End the report with a Top recommendation section.

Once the user picks a candidate, run the /grilling skill to walk the design tree with them.

Side effects happen inline as decisions crystallize — run the /domain-modeling skill to keep the domain model current as you go.