/design-an-interface

From "Design It Twice" (Ousterhout): your first idea is rarely the best. The value is in contrast — not in any single design.

Step 1 — Gather Requirements

Shallow intake produces shallow designs. Ask these specifically — not just "what does it do?":

1. What is the one-sentence job of this module?
2. Who are the callers? (other modules, end users, tests, CLI, external systems)
3. Walk me through the happy path in code — what does the call site actually look like?
4. What are the failure modes? What can go wrong, and who handles it?
5. What must the interface hide? What should callers never need to know about?
6. Any hard constraints? (performance, compatibility with existing patterns, language idioms)
7. Is there a "most common case" that should be especially ergonomic?

Don't proceed until you have real answers. One vague sentence is not enough.

Step 2 — Generate Designs

If the runtime provides fresh isolated worker contexts: spawn the three designs within its supported bounded controls. Each agent gets the requirements plus its assigned lens and must produce a design that would surprise the others. Brief them to actively resist the obvious answer.

Without fresh contexts, produce the contrasting designs sequentially and complete each before the next. Label this a useful correlated same-context fallback; prior visible designs prevent a claim of independent generation.

Produce 3 radically different designs. Radically different means different information hiding boundaries — not just different method names or parameter orders. Three designs that all accept a config struct and return a result are not radically different, even if the method names differ.

Use these lenses to force divergence:

Add a 4th for domain-specific shapes (event-driven, streaming, builder, type-state) when relevant.

For each design, produce:

• Interface — concrete method signatures, types, function signatures. Not schematic.
• Usage example — real call-site code for: happy path, error case, one awkward case.
• What this hides — complexity that lives inside, invisible to callers.
• What this exposes — decisions or knowledge pushed onto the caller.
• Where it shines / breaks down — 1–3 honest sentences.

Step 3 — Compare

Fill this table, then write prose.

The table shows what. The prose explains why it matters. Go deep on where the designs diverge most — depth, misuse resistance, evolution over time, and the awkward case each design can't handle cleanly. Don't soften it. Say which designs have real problems.

Apply the Evaluation Criteria from the Reference section below.

Step 4 — Synthesize

This is the highest-value output. Produce something concrete:

1. State your recommendation and why, referencing the comparison.
2. Write the synthesized design — concrete signatures, not description. If one design wins outright, restate it as a clean spec. If the answer is "take X's shape, borrow Y's error handling, add Z's escape hatch," write that out.
3. Name the one thing to get right — the decision that, if wrong, causes the most pain later.

Close by asking: "Does this fit your primary use case? Anything from the other designs worth keeping?"

Reference

Use these during Step 3. Don't apply them during generation.

Evaluation Criteria (APOSD)

• Interface simplicity — fewer methods, simpler params → easier to learn, harder to misuse.
• Depth — small interface hiding large complexity = deep module (good). Large interface over thin implementation = shallow module (avoid).
• General-purpose vs. specialized — can it handle adjacent use cases without changes? Beware over-generalization, but also beware interfaces that lock in today's assumptions.
• Implementation efficiency — does the interface allow an efficient implementation, or force awkward internals?
• Ease of correct use — the best interfaces make the right thing the natural thing.

Anti-Patterns

• Convergent designs — if all three designs are the same module with different names, you've failed. Start over with harder constraints.
• Skipping comparison — generating without comparing is just brainstorming. The value is in the contrast.
• Implementing — this skill is about interface shape. Don't write internals.
• Premature synthesis — don't merge designs during generation. Let them stay fully different until Step 4.
• Vague trade-offs — "more flexible" means nothing. More flexible how, for whom, at what cost?

Human output. This skill's handler-facing output obeys the human-output contract (human-output/SKILL.md).

Next skills. On completion, run the Next Skills protocol (next-skills/SKILL.md): surface the next-skills recommendations from front-matter for the caller to pick. Offer only — never auto-invoke.

Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.