module-designlisted

# Module Design Use these criteria when a module's responsibilities, interface, dependencies, or test seams are unclear. Adapt them to the repository's language, framework, and established architecture. ## Workflow 1. Inspect callers, implementation, tests, data flow, lifecycle, and existing conventions. 2. State the behavior the module should own and the knowledge callers should not need. 3. Map dependencies and direction: which dependencies are stable, which vary, and which side should own the abstraction. 4. Consider at least two plausible designs when the boundary is consequential. See [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md). 5. Compare designs by interface size, cohesion, coupling, locality, dependency direction, testability, migration risk, and fit with the codebase. 6. Recommend the smallest design that gives clear ownership and a stable behavioral seam. ## Decision criteria - Prefer a deep module: substantial behavior behind a small, stable interface. - Keep behavior and the state or rules it governs local when that improves understanding. - Put tests at stable behavioral seams so internal refactoring does not rewrite them. - Inject dependencies when substitution, isolation, or lifecycle ownership requires it; avoid indirection that has only one fixed implementation and no testing value. - Make dependency direction reflect ownership of policy rather than incidental call direction. - Avoid abstractions that merely rename or forward calls. - Reduce scattered busin