deep-moduleslisted

# Deep Modules How to deepen a cluster of shallow modules safely, given its dependencies. The aim is testability and AI-navigability. Load skill: [code-design](../code-design/SKILL.md). ## Signals - 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 (no **locality**)? - 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? A "yes, concentrates" is the signal you want. ## Dependency categories When assessing a deep-module candidate, classify its dependencies. The category determines how the deepened module is tested across its seam. ### 1. In-process Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed. ### 2. Local-substitutable Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface. ### 3. Remote but owned (Ports & Adapters) Your