Immutable. This exact content is served forever at /api/v1/blob/770365c107ae2306.
--- name: design-it-twice description: 'Use when asked to design a module interface, seam, or testable boundary. Produce compared alternative interface designs using explicit deep-module vocabulary and deliberately placed seams. Not for UI direction picking — use design. No source or remote-system changes.' --- # Design it twice ## Contract | Field | Bound contract | |---|---| | Trigger | Design a module interface, seam, or testable boundary. | | Authority | Read-only: no file, VCS, credential, paid, published, deployed, or remote mutation. Design guidance only. | | Side effect | None. No artifacts are written; output is a design comparison and recommendation in chat. | | Done | The design uses explicit deep-module vocabulary and deliberately placed seams. | ## Inputs - A module, cluster, or boundary to design, named by the user or identified from context. Required. - The codebase's primary language and any second language family the project owns. Optional, but needed for cross-language interface sketches. - Existing callers and dependencies of the target. Optional; improves constraint framing. ## Procedure Use these terms exactly. Do not substitute "component," "service," "API," or "boundary." - Module -- anything with an interface and an implementation: a function, class, package, crate, or tier-spanning slice. - Interface -- everything a caller must know to use the module correctly: type signature, invariants, ordering constraints, error modes, required configuration, and performance characteristics. - Implementation -- the body of code inside a module. - Depth -- power at the interface: the amount of behaviour a caller can exercise per unit of interface they must learn. Deep = much behaviour behind a small interface; shallow = interface nearly as complex as implementation. - Seam -- a place where behaviour can be altered without editing in that place. The location at which a module's interface lives; choosing where to put the seam is a design decision separate from the implementation. - Adapter -- a concrete thing that satisfies an interface at a seam; describes role, not substance. - Leverage -- what callers get from depth: more capability per unit of interface learned. - Locality -- what maintainers get from depth: change, bugs, and verification concentrate in one place rather than spreading across callers. Before designing, classify the target's dependencies. The category determines how the deepened module is tested across its seam. 1. **In-process** — pure computation, in-memory state, no I/O. Always deepenable; merge the modules and test through the new interface directly. No adapter needed. 2. **Local-substitutable** — dependencies with local test stand-ins (PGLite, in-memory filesystem, Testcontainers). Deepenable when the stand-in exists; the seam stays internal. 3. **Remote but owned** — owned services across a network boundary. Define a port at the seam; inject the transport as an adapter. In-memory adapter in tests, HTTP/gRPC/queue adapter in production. 4. **True external** — third-party services the team does not control. Take the dependency as an injected port; tests provide a mock adapter. Seam discipline: one adapter means a hypothetical seam; two adapters mean a real one. Do not introduce a port unless at least two adapters are justified. 1. **Frame the problem space.** Write a user-facing explanation of the chosen target: the constraints any new interface must satisfy, the dependencies it relies on and which category each falls into, and a rough illustrative code sketch that makes the constraints concrete, not a proposal. Use the codebase's primary language; for polyglot projects, sketch in each owned language family. Show this to the user. **Done when:** the framing states constraints, per-dependency categories, and a concrete sketch shown to the user. 2. **Spawn three or more parallel alternative designs.** Each must produce a radically different interface for the module. Give each a separate technical brief: file paths, coupling details, dependency category, and what sits behind the seam. Give each a distinct design constraint: - Minimize the interface: one to three entry points maximum, maximise leverage per entry point. - Maximise flexibility: support many use cases and extension. - Optimise for the most common caller: make the default case trivial. - Design around ports and adapters for cross-seam dependencies, when applicable. Each design outputs: (a) the interface — types, methods, params, invariants, ordering, error modes, expressed in the codebase's language; (b) a usage example showing how callers use it; (c) what the implementation hides behind the seam; (d) dependency strategy and adapters; (e) trade-offs — where leverage is high, where it is thin. **Done when:** three or more designs are produced, each radically different and carrying all five output fields. 3. **Present and compare.** Present the designs sequentially so the user can absorb each one, then compare them in prose. Contrast by depth (power at the interface), locality (where change concentrates), and seam placement. **Done when:** designs are presented sequentially and compared by depth, locality, and seam placement. 4. **Recommend.** Give an opinionated recommendation that names the strongest design and explains why. If elements from different designs would combine well, propose a hybrid. Be decisive: deliver a strong read, not a menu. **Done when:** one recommendation names the strongest design or a hybrid with its reason. ## Failure and recovery - **Ambiguous target.** If the user does not name a module or boundary to design, stop and ask which target to design. Do not invent a target. - **Unclassifiable dependencies.** If a dependency category cannot be determined from available context, state which category is unknown and design conservatively: treat an unknown external dependency as true-external with an injected port. - **Convergent designs.** If the parallel designs are not radically different, re-dispatch with sharper, more divergent constraints. A menu of near-identical designs fails the done predicate. - **Non-mutation.** This skill writes nothing. If any step would require editing a file, stop; the output is design guidance only. ## Output A design comparison in chat: problem-space framing, three or more radically different interface designs, a prose comparison by depth, locality, and seam placement, and one opinionated recommendation — ordered frame → diverge → compare → recommend, with no files written.