Codebase Design

Concentrate complexity behind useful interfaces. A good module gives callers substantial capability while keeping knowledge, change, bugs, and verification local.

When another skill loads this one, apply the vocabulary and analysis below inside that skill's workflow and output format. When invoked directly, complete the full workflow and return the module-design report.

Workflow

1. Frame the module

Identify the module under review, its responsibility, callers, dependencies, public entry points, observable behavior, and constraints. A module may be a function, class, component, package, service, feature, or tier-spanning slice.

Use the repository's framework terms for concrete artifacts and module for their design role.

Complete when: the module, its callers, its current contract, and the desired outcome are explicit.

2. Map interface burden

List everything a caller must know to use the module correctly:

• operations and data shapes;
• invariants and valid ordering;
• errors and recovery responsibilities;
• configuration and lifecycle;
• performance or concurrency characteristics;
• implementation details repeated or coordinated by callers.

Treat the interface as this full burden, not only its type signature or network API. Trace each claim to callers, exports, tests, or runtime behavior.

Complete when: every demonstrated piece of caller knowledge is accounted for and implementation knowledge leaking through the interface is identified.

3. Assess depth and locality

Judge the behavior centralized by the module against the interface callers must learn. Apply the deletion test: if the module disappeared, would its complexity spread into callers or vanish? Spreading complexity indicates useful leverage; vanishing complexity suggests a shallow pass-through.

Look for repeated orchestration, change amplification, duplicated error handling, scattered policy, and tests that bypass the public interface. Measure depth through caller knowledge and centralized behavior rather than implementation size.

Complete when: the module's depth, leverage, and locality are supported by specific caller and change evidence.

4. Decide what belongs together

For a proposed split or join, inventory the nonobvious knowledge each phase or module needs: format rules, invariants, policy decisions, and reasons to change. Trace duplicated knowledge, including back-door assumptions absent from signatures, to concrete code or contracts. Walk a representative format, invariant, or policy change: which implementations and callers must change together?

Compare keeping, joining, and splitting the relevant responsibilities by total caller and implementation burden: interfaces and coordination added, knowledge hidden or duplicated, change amplification, locality, and demonstrated independent variability. Prefer one owner for knowledge that must change together; preserve meaningful responsibilities that can vary independently and necessary caller policy. Execution order, LOC, or short methods alone do not justify a split; shared input or execution proximity alone do not justify a join.

For example, reading and parsing stages that both encode the same wire grammar may belong behind one protocol interface. Parsing and authorization sharing request data still need distinct trust responsibilities and a narrow validated contract. Preserve ownership, trust/security, deployment, and generated/framework-required boundaries through explicit contracts rather than collapsing them to remove overlap. If evidence is missing, identify the change or caller trace needed before choosing.

Complete when: each proposed grouping has a knowledge/change trace and a join-versus-split rationale, including what remains independently owned. When composed by another workflow, keep this analysis in its existing output format.

5. Inspect seams and adapters

A seam is a place where behavior can vary without editing the caller. An adapter is a concrete implementation occupying a role at that seam. Reserve boundary for domain, ownership, process, deployment, or trust boundaries.

Find where dependencies are accepted versus constructed, where tests and production use different paths, and where callers select or coordinate implementations. Treat a seam as earned when variation is demonstrated by multiple adapters, a test double, a platform difference, or a known source of change.

Complete when: each proposed or existing seam has a demonstrated source of variation and its placement is justified independently from its interface design.

6. Design a deeper alternative

Move stable policy and repeated knowledge behind the interface while preserving necessary caller control. Prefer the smallest coherent interface that owns the full responsibility. Compare the current design with the proposed design through:

• caller knowledge removed or added;
• behavior and policy centralized;
• changes localized;
• errors and invariants owned;
• testing through the same interface callers use;
• migration cost and compatibility.

When one representation forces repeated empty, root, or sentinel checks across ordinary operations, compare it with an invariant that lets the normal operation handle those cases. For example, an empty range can represent no visible selection when copying or deleting that range already preserves the required behavior. Trace the branches and caller obligations removed, not just the reduced if count. Retain meaningful business, authorization, failure, and protocol distinctions; absence and an empty value are interchangeable only when the contract makes them so. A surprising sentinel, a more complicated common path, or one cheap local guard does not justify a representation change. Keep error-contract decisions with their owner and language-specific state modeling with typescript; use refactor for authorized behavior-preserving implementation.

Keep existing behavior and public APIs unless the user authorizes a contract change. Avoid an abstraction when it only renames operations, forwards calls, or anticipates variation without evidence.

Complete when: the recommendation states what moves behind the interface, what remains caller-owned, and why the resulting module provides more leverage.

7. Define verification

Specify how to prove the design improvement. Prefer observable checks such as fewer caller responsibilities, removal of repeated coordination, tests crossing the public interface, localized future changes, or elimination of implementation-aware call sites. For a representation change, check normal, empty/root, and transition cases through the public interface, including preserved distinctions and any caller knowledge actually removed.

Route a cross-system or hard-to-reverse decision to architect. Route authorized behavior-preserving implementation work to refactor.

Complete when: the proposed interface, migration boundary, and checks for behavior and design improvement are concrete enough to implement or review.

Vocabulary

• Module: an interface plus an implementation.
• Interface: everything callers must know to use the module correctly.
• Implementation: behavior hidden behind the interface.
• Depth: useful behavior provided per unit of interface burden.
• Seam: a place where behavior can vary without editing the caller.
• Adapter: a concrete implementation filling a role at a seam.
• Leverage: capability callers receive per unit of interface they must learn.
• Locality: concentration of knowledge, change, bugs, and verification.
• Boundary: a domain, ownership, process, deployment, or trust division.

Report

When invoked directly, return:

1. Module and callers — scope, responsibility, dependencies, and evidence.
2. Interface burden — what callers currently must know.
3. Diagnosis — depth, locality, leaks, seams, adapters, and any grouping decision.
4. Recommended interface — responsibilities moved, retained, or removed.
5. Migration and verification — compatibility, sequence, tests, and success checks.

Describe observations before judgments. Tie every recommendation to leverage, locality, testability, or a demonstrated architectural constraint.