Design an Interface

Philosophy

Every interface design involves tradeoffs you cannot see from a single perspective. Designing it twice (or three times) with radically different constraints forces you to explore the design space before committing. This skill spawns parallel sub-agents, each constrained differently, then compares and synthesizes.

Workflow: 5 Phases

Phase 1: Gather Requirements

Before spawning any sub-agents, clarify:

• What problem does this interface solve?
• Who are the callers? What do they need?
• What are the invariants the interface must preserve?
• What are the performance / ergonomic / safety constraints?

Do NOT start designing until requirements are agreed upon.

Phase 2: Spawn Divergent Sub-Agents

Launch 3+ parallel sub-agents with the host's delegation facility, each given the same requirements but a different constraint set. In Codex, use parallel spawn_agent calls; in Claude Code, use parallel Agent calls. If the host has no sub-agent facility, stop and explain that the workflow cannot preserve its required independent design passes. Constraints must force radically different designs -- not minor variations. See constraints.md for examples.

Each sub-agent produces:

• Interface definition (function signatures, types, module API)
• Usage example for the most common case
• One paragraph on the tradeoff it optimized for

Phase 3: Present Designs

Show all designs side-by-side. Label each by its primary constraint. Do not editorialize yet -- let the user see the raw options.

Phase 4: Comparative Evaluation

Evaluate every design against Ousterhout's criteria. See evaluation-criteria.md for the full rubric. Score each design on:

• Depth (small interface, rich implementation)
• Simplicity of the common case
• Resistance to misuse
• General-purpose vs specialized tradeoff
• Implementation efficiency

Phase 5: Synthesize

Combine the best elements into a final design. Explain which parts came from which design and why. The synthesis is often none of the originals -- it is a new design informed by all of them.

Rules

• Never present fewer than 3 designs.
• Designs must be structurally different, not cosmetic variations.
• Evaluate on caller ergonomics, not implementation convenience.
• Prefer deep modules: small interface surface, rich behavior behind it.
• If all designs converge, your constraints were too similar -- re-run with harder constraints.

What You Get

• Three or more structurally distinct interface designs, each optimized for a different constraint set.
• A side-by-side comparative evaluation scored against Ousterhout's criteria (depth, simplicity, misuse resistance).
• A synthesized final design that combines the strongest elements from all candidates, with rationale for each choice.

Sub-files