architecture-deepening

To identify shallow modules, analyze interface-to-implementation shallowness signals across the codebase to find public interfaces that leak implementation details and force callers to manage complexity. This treats shallow modules as architectural candidates rather than style violations.

You need to refactor module interfaces when teams repeatedly ask how to use modules correctly, new contributors report onboarding confusion, or before major feature pushes. Post-defect-fix reviews also benefit from interface deepening to prevent recurring implementation leaks.

Find seams for deepening by analyzing data, protocol, and temporal dependencies to determine where responsibility can be moved behind a cleaner interface. This seam analysis enables you to isolate complexity without disrupting the entire module architecture.

The best way to propose deepened interface alternatives is through an iterative collaboration process that generates interface alternatives with deletion tests, evaluates explicit trade-offs, and documents a deepening decision covering the migration path and next steps.

Yes, you can use architecture deepening for new contributor onboarding by targeting areas where new contributors report confusion. It analyzes internally leaky modules and proposes deepened interfaces to reduce the architectural complexity new team members must learn.

Treating shallow modules as code style violations limits architectural improvement because it misses underlying interface-to-implementation leaks. Architecture deepening instead focuses on identifying seams and leverage points to move responsibility behind a cleaner abstraction.