| name | codebase-design-and-deep-modules |
| description | Use when the task involves architecture, module design, refactors, interface boundaries, adapters, dependency direction, deep module design, deletion tests, locality, leverage, encapsulation, and codebase structure decisions before or during APIVR planning and review. |
| activation | Activate when the description trigger applies to the current task. |
| required_inputs | Task request, relevant repository context, constraints, and authority dependencies. |
| required_outputs | Skill-specific artifact, verification evidence, canonical verdict, and next action. |
| authority_dependencies | 00_start_here/SOURCE_OF_TRUTH.md; 10_governance/APIVR_EXECUTION_LIFECYCLE.md; 10_governance/source_of_truth/Elite_Build_Goals_v3.md. |
| evidence_requirements | Executed checks or an honest Unknown, Not Run, or Blocked state for every material claim. |
Codebase Design And Deep Modules
Use this skill when the shape of the code matters as much as the code itself.
Design Checks
- Module depth: a simple interface hides meaningful complexity.
- Locality: related decisions live near each other.
- Dependency direction: core policy does not depend on delivery details.
- Adapter boundary: third-party, UI, persistence, and transport concerns stay replaceable.
- Deletion test: removing the feature or provider has a predictable blast radius.
- Naming: code uses the project domain glossary.
- Escape hatches: special cases are explicit, not scattered.
Decision Flow
flowchart TD
A["Design or refactor needed"] --> B{"Is the business rule duplicated or scattered?"}
B -- "Yes" --> C["Create or strengthen core module"]
B -- "No" --> D{"Is integration detail leaking inward?"}
D -- "Yes" --> E["Add adapter boundary"]
D -- "No" --> F{"Can the change be deleted cleanly?"}
F -- "No" --> G["Narrow interface and improve locality"]
F -- "Yes" --> H["Proceed with APIVR plan"]
Worked Example
Scenario: Three providers calculate shipping estimates differently.
- Bad design: provider-specific logic in checkout UI.
- Better design:
ShippingQuoteService exposes one domain method and provider adapters implement external details.
- Evidence: contract tests cover provider-independent behavior.
- Release gate: architecture passes only when checkout no longer knows provider-specific quirks.
