Design deep modules

Design Deep Modules

Objective

Improve a cohesive boundary so callers rely on a small, stable contract while the module owns meaningful functionality, policy, coordination, validation, dependency handling, and change-prone decisions.

Apply the lens within the primary task rather than redefining it. Treat review as input to a boundary decision, not as a search for more abstractions. Recommend the smallest durable change supported by evidence.

Depth Standard

Optimize for depth, not size.

Judge the interface by the total knowledge required to use it correctly, including:

• operations, types, events, options, and configuration
• preconditions, side effects, failure semantics, and consistency guarantees
• ordering, lifecycle, ownership, cleanup, and compatibility expectations
• internal concepts or call sequences callers must reconstruct

Judge the implementation by the useful, cohesive knowledge it hides. Count domain rules, workflows, algorithms, state transitions, integration differences, validation, authorization, retries, transactions, caching, observability, and recovery behavior as depth when they belong to the same abstraction.

Require both depth and cohesion. Do not treat a small interface as justification for a god module, or a large file as proof that a boundary should be split.

Do not confuse a deep module with a deployment topology. Apply the lens within a process, package, library, plugin, or service boundary without using it alone to justify distribution or independent deployment.

Generalize only when current callers, repeated use, or a demonstrated change axis supports it. Prefer a focused boundary over a speculative universal interface.

Apply The Boundary Lens

Use these decisions inside the workflow of the primary task. When the requested outcome is a boundary design or assessment, let the lens guide the full analysis. Otherwise, inspect and surface only the boundary concerns that materially affect the requested result.

Do not turn every touched file, type, or dependency into a broader architecture review.

1. Inspect Boundary Evidence

Identify the candidate boundary, its callers, supported workflows, public entry points, and compatibility surfaces. Inspect repository documentation, exports, call sites, dependency direction, tests, and change history when they can answer the design question.

Distinguish observed behavior from assumptions. Do not infer a public contract from naming or file layout alone.

2. Map Interface Burden And Hidden Knowledge

List what each caller must know or coordinate. Include informal contract knowledge, not only public symbols.

List the decisions the module owns or should own. Group decisions that change for the same reason, and separate decisions with independent change axes.

Ask:

• What should callers be able to forget after crossing this boundary?
• Which workflow, rule, or integration detail becomes private?
• Does the interface express caller intent or expose implementation steps?
• Do callers repeat sequencing, branching, validation, mapping, retries, transactions, cache invalidation, or cleanup?
• Do framework, transport, persistence, UI, or vendor types leak into policy that should outlive them?
• Are safety-relevant consequences visible even when their mechanics are hidden?

3. Choose A Boundary Move

Choose one primary move. Combine moves only when the evidence shows distinct boundary problems.

Move	Choose when	Required result
preserve	Existing complexity protects a contract, policy, dependency direction, external-effect seam, compatibility promise, diagnostics, or recovery behavior.	Keep the protected knowledge and explain why callers benefit from the boundary.
deepen	Callers reconstruct workflow or internal decisions, the public surface is unstable, or infrastructure details leak outward.	Move coherent knowledge inward and expose intent-level operations with explicit consequences.
merge	A layer, wrapper, service, or interface mostly passes through calls and owns no distinct abstraction or contract.	Remove ceremony while preserving any real translation, policy, or compatibility behavior.
split	Internals have low cohesion, unrelated change axes, conflicting ownership, or independently evolving policies despite a small public surface.	Create cohesive boundaries without making callers orchestrate the separated internals.
delay	The change axis, caller need, alternative implementation, or stable contract is not yet demonstrated.	Keep the design focused and record the evidence that would justify a future abstraction.

Reject changes that merely move code, rename layers, add an interface for hypothetical variation, or reduce file count without reducing caller knowledge or protecting a real decision.

4. Define The Boundary Contract

Define:

• callers and caller-intent operations
• formal and informal interface contract
• hidden decisions and internal responsibilities
• boundary data free of avoidable outer-framework or vendor coupling
• dependency direction and ownership of abstractions
• compatibility surfaces and error semantics
• non-goals and intentionally visible consequences

Point dependencies toward stable policy and away from replaceable details. Let the policy owner define an abstraction only when inversion protects a real boundary, test seam, or compatibility promise.

5. Make The Boundary Enforceable

Use the strongest practical mechanism already supported by the language, build, or repository: visibility controls, explicit exports, package rules, dependency constraints, architecture tests, lint rules, or focused review conventions.

Prefer machine-enforced restrictions when the repository can support them. Do not propose a new dependency or governance layer when an existing mechanism can express the contract.

6. Verify The Boundary Effect

Select only the evidence needed to show that the affected boundary contract holds. Leave test construction and the overall verification workflow to the guidance that owns the primary task.

• verify hidden rules and state transitions through the public contract
• verify adapters at the external boundary they translate
• verify shared public contracts across independently changing consumers and providers
• check forbidden dependencies, private imports, cycles, and exported surfaces when they define the boundary
• compare representative callers before and after; confirm they know less and perform less choreography
• confirm that internal changes along the intended change axis can preserve the public contract

Avoid over-mocking internal collaboration. Fake or mock unstable external effects only when needed to verify policy separately from infrastructure.

Boundary-Specific Migration

When the primary task migrates a boundary:

1. Define the target public entry point and compatibility expectations.
2. Prevent new violations when practical without requiring the existing baseline to be clean first.
3. Move callers in small, behavior-preserving slices.
4. Keep temporary adapters, abstractions, or toggles explicit, owned, and removable.
5. Remove direct internal access, obsolete entry points, and temporary machinery before making the migrated boundary authoritative.

Do not propose a big-bang rewrite when a compatible incremental path can establish the same boundary. Do not leave migration scaffolding as an accidental permanent API.

Uncertainty And Stop Conditions

State assumptions and offer compatible alternatives when missing evidence does not prevent a useful recommendation.

Ask a targeted question before selecting or implementing a boundary change only when the answer materially affects:

• supported callers or compatibility promises
• safety, authorization, consistency, durability, or data-loss semantics
• ownership or dependency direction
• whether complexity is shallow ceremony or protected depth

Report an investigation as a follow-up instead of a finding when evidence does not prove the problem. Preserve existing observable behavior unless the requested outcome explicitly changes the contract.

Keep The Responsibility Bounded

Own decisions about caller knowledge, hidden decisions, cohesion, public surfaces, dependency direction, contract stability, and boundary enforcement.

Do not own the overall change scope, implementation sequence, review format, migration program, or testing cycle. Apply the relevant task or domain guidance separately without requiring another Skill or coupling to one by name.

Composition And Reporting

Follow the workflow and output format of the primary task.

Keep routine boundary analysis implicit. When a boundary decision materially affects the result, make the chosen move, caller impact, supporting evidence, contract or compatibility consequences, and relevant verification or uncertainty visible.

Do not require dedicated headings, classifications, or a separate architecture report unless the user requested boundary design or assessment as the primary outcome. Even then, adapt the response to the user's requested form and omit irrelevant detail.