design-an-interface

Step 1: Gather requirements

Before spawning anything, answer in the conversation:

• What problem does the module solve?
• Who calls it? (other modules, external users, tests)
• What are the key operations?
• What constraints exist? (performance, compatibility, existing patterns)
• What should stay hidden inside vs be exposed?

If the user did not supply all of these, ask — one round, 1–3 questions max, per the ask-vs-infer rule.

Step 2: Spawn parallel design agents

Use Agent(subagent_type=general-purpose) for 3–4 agents in one message so they run concurrently. Each agent gets the same requirements brief plus one divergent constraint:

• Agent 1: "Minimize method count — 1 to 3 entry points max."
• Agent 2: "Maximize flexibility — support many extension points and composition."
• Agent 3: "Optimize for the single most common caller — make the default case trivial and the advanced case possible."
• Agent 4 (optional): "Design around a ports-and-adapters boundary — interface is the port, concrete implementations are adapters."

Each agent returns:

1. Interface signature (types, methods, params)
2. One worked usage example showing a real caller
3. What complexity this design keeps internal
4. Trade-offs — what it's bad at

Step 3: Present sequentially

Show the three designs one after another. Let the user read each before the next. Do not lead with the comparison — the value is in feeling the shape of each option first.

Step 4: Compare in prose

After all three are on the page, compare them on:

• Simplicity — fewer methods and simpler params are easier to learn and harder to misuse
• Depth — small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
• Generality vs specialization — does it cover the real use case without overfitting?
• Efficiency of the shape — does the interface let the implementation be efficient, or force awkward internals?
• Misuse surface — what can a caller do wrong?

Prose, not a table. Highlight where the designs diverge most sharply — that is where the interesting trade-off lives.

Step 5: Recommend

Be opinionated. Pick one, or propose a hybrid that takes specific elements from multiple designs. State the reason in one paragraph. The user wants a strong read, not a menu.

Step 6: Capture the decision

Once the user picks:

• Append to .gsd/DECISIONS.md with the chosen shape and the reason.
• If a slice is active, update S##-CONTEXT.md with the interface sketch.
• Do not write the implementation — that happens during execute.