design-an-interface

Gather concrete requirements first: callers, failure modes, and the most common case. Then generate multiple radically different designs with different information-hiding boundaries, compare them on operation count and caller knowledge required, and synthesize a final recommendation.

Design it twice, from John Ousterhout's A Philosophy of Software Design, means producing multiple genuinely different interface candidates instead of committing to your first idea. The value comes from the contrast between designs, which reveals trade-offs a single design hides.

Use a comparison table covering number of operations, caller knowledge required, error handling location, composability, and fit for the common case. Then apply criteria like interface simplicity, module depth, and ease of correct use to explain why differences matter.

Skip it when the interface is already locked in, when the module is trivial with an obvious shape, or when you need an implementation plan rather than design options. For turning a chosen design into execution steps, use a planning skill instead.

Radically different designs have different information-hiding boundaries, not just different method names or parameter orders. For example, a minimal two-method surface versus exposed composable primitives versus a one-line common-case API represent real divergence.