Codebase Design

Choose a module shape that puts substantial behavior behind a small interface at a clean seam. Optimize for leverage for callers, locality for maintainers, and testability through the same interface callers use.

Authority and composition

Treat this as a read-only design workflow. Inspect code, tests, and architecture material; return a recommendation in the conversation by default. Do not edit implementation files, claim an issue, change tracker state, persist a design, commit, push, or review a completed change from this skill.

• Before to-spec, use this skill when the module interface or architectural seam is not settled. Pass the recommendation and its resolution status to to-spec; let that skill record a resolved decision or keep an unresolved recommendation open.
• Consume accepted domain vocabulary without invoking another workflow. If conflicting terms, identity, lifecycle, invariants, relationships, states, or domain boundaries would materially change the interface alternatives, return that model pressure to domain-modeling before selecting a seam; resume only from an established model or with the affected choice explicitly unresolved.
• If a supplied planning document declares kind: "spec-explainer", normative: false, or an equivalent warning, read only enough metadata to resolve derived_from and use the authority for design constraints. The only richer input allowed is a local-work-item: use its writable scope and source IDs to bound the recommendation, but do not treat its non-normative prose as an approved interface decision. Ignore every other non-normative body.
• During issue-backed implementation, use this skill only after the outer work-github-issue workflow reports an already-held valid implementation lease. If no lease is held, return control without claiming one. Enter after a diagnosis or validated hotspot establishes that module reshaping is needed and before tdd when the ticket still needs a module-shape recommendation.
• If the recommendation would change approved behavior, an accepted architecture decision, ticket boundaries, or dependencies, stop implementation and return the recommendation to the planning workflow before editing.
• Treat private, in-bounds implementation structure as delegated to the implementer by default when it preserves approved behavior, public interfaces, accepted architecture, ticket boundaries, and dependencies. Require explicit acceptance only when the recommendation changes one of those contracts or another approval-gated decision. Do not present an out-of-bounds agent preference as accepted.
• Use tdd to implement the selected interface through observable behavior. Let code-review assess the result only against repository Standards and the originating Spec, not against an unapproved recommendation from this skill.
• When the user explicitly requests a durable design decision, use documenting-work to resolve its authority, destination, metadata, and write authorization, then leave the actual write to the authorized outer workflow.

A recommendation is resolved when existing authority fixes it, it is a private in-bounds implementation choice, an accepted source delegates it within named limits, or explicit user or repository authority accepts it. Other recommendations remain proposed.