/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