improve-codebase-architecture

Refactoring shallow modules involves identifying deepening opportunities that replace weak designs with higher-depth interfaces, enforcing seam and adapter discipline to concentrate knowledge and improve testability.

Shallow modules have weak locality and seams that don't support effective testing, while deepening replaces them with stable interface-level test surfaces that pass the deletion test, concentrating verification where it belongs.

Consolidating tightly-coupled modules requires scanning for deepening candidates, validating dependency categories, and applying ports and adapters strategy to establish stable seams that support AI-navigable maintenance.

Yes, the Design It Twice approach guides interface exploration by generating and comparing radically different interface shapes for a chosen deepening candidate, aligning with domain vocabulary and existing ADR decisions.

Apply ports and adapters when improving architecture to replace shallow module designs, enforce seam and adapter discipline, and focus validation on interface-level test surfaces using the deletion test for AI-navigable maintenance.

Validating seam placement requires running a grilling loop to check constraints, dependency categories, adapter strategy, and the test surface for the deepened module against the deletion test.