# Design It Twice

Explore several interfaces for one module in parallel, because the first idea is unlikely to be the
best. Uses the vocabulary in [SKILL.md](SKILL.md): **module**, **interface**, **seam**, **adapter**,
**leverage**.

## Gate: is this worth the ceremony?

This pattern spends several agents on one decision. It earns that only where the solution space is
genuinely wide and the choice is expensive to reverse:

- **Run it when** the module is load-bearing, several plausibly-good interfaces exist, and callers
  will be written against whichever one wins.
- **Skip it when** one obvious interface fits, the module is small, or the decision is cheap to
  change later. Design it once, in this context window, and move on.

A single agent that finishes the job in one pass should just finish it. Reach for the fan-out for
breadth, not for routine work.

## Process

### 1. Frame the problem space

Before spawning anything, write a user-facing explanation of the problem space:

- The constraints any new interface must satisfy
- The dependencies it relies on, and their category from [DEEPENING.md](DEEPENING.md)
- A rough code sketch to make the constraints concrete. This grounds the discussion; it is not a
  proposal.

Show it, then proceed immediately. The reading happens while the agents work.

### 2. Spawn the designers

Spawn three or more agents in parallel, each producing a **radically different** interface. Give each
a separate technical brief (file paths, coupling details, dependency category, what sits behind the
seam) and a different design constraint:

| Agent | Constraint |
|---|---|
| 1 | Minimise the interface: one to three entry points, maximum leverage per entry point |
| 2 | Maximise flexibility: support many use cases and extension |
| 3 | Optimise for the most common caller: make the default case trivial |
| 4 (where relevant) | Design around ports and adapters for cross-seam dependencies |

**These agents design, they do not write.** Each returns a proposal; none edits a file, so there is
no file ownership to divide and no chance of a collision. Say so in each brief.

Include both the [SKILL.md](SKILL.md) vocabulary and the project's `CONTEXT.md` vocabulary in every
brief, so the proposals name things consistently and can actually be compared.

Each agent returns:

1. The interface: types, entry points, params, plus invariants, ordering, and error modes
2. A usage example showing how callers use it
3. What the implementation hides behind the seam
4. Its dependency strategy and adapters
5. Trade-offs: where leverage is high, where it is thin

### 3. Present and compare

Present the designs one at a time so each can be absorbed, then compare them in prose along
**depth** (leverage at the interface), **locality** (where change concentrates), and **seam
placement**.

Finish with your own recommendation: which design is strongest and why. Where elements from different
designs combine well, propose the hybrid. Be opinionated. The point of the fan-out is a strong read,
not a menu.