design-an-interface

Apply "Design It Twice" (Ousterhout, A Philosophy of Software Design): the first interface is rarely the best. Generate at least three radically different shapes for the same module, then compare on depth and ease of correct use. Implementation is out of scope — this skill stops at the contract.

Run discovery before generation. When the module already has callers, dispatch an Explore agent to enumerate them (fd for files, git grep/ast-grep for usage sites) so the constraint set reflects real consumers, not imagined ones.

Modality vs adjacent skills: This is divergent generation under enforced contrast. Implementation planning is convergent and execution-oriented. Clarifying-question protocol is VS-shaped clarification on a single direction. Pick this skill when the answer is "we don't yet know the right shape" and the value is in deliberate contrast across N candidates.

Workflow

1. Frame the contract

Capture, in this order, before any design work:

• The problem the module solves, in one sentence.
• The callers — peer modules, external consumers, tests — and which one is primary.
• The key operations, ranked by frequency.
• Constraints: performance budget, compatibility surface, existing patterns the module must echo.
• The information boundary: what the module hides versus what it must expose.

If any item is unknown, surface it as a question before proceeding. Designing on assumed callers wastes the parallel-generation budget.

2. Generate divergent designs in parallel

Dispatch 3–4 Explore agents simultaneously, each with a distinct constraint that forces divergence. Suggested constraint slate:

• Agent A: minimise the surface — 1–3 entry points maximum.
• Agent B: maximise generality — accept many shapes of input.
• Agent C: optimise for the dominant call site at the cost of the rare one.
• Agent D: borrow shape from a named external paradigm (iterator, builder, capability handle, effect handler).

Each agent returns: contract signature, one realistic call-site example, what the design hides internally, and the trade-offs it accepts.