design-an-interface

name	design-an-interface
description	Generates and compares parallel interface designs (Ousterhout 'Design It Twice'). Triggers: design API, interface options, compare modules, design it twice.
user-invocable	true
effort	high
argument-hint	[module or interface to design]
allowed-tools	Read, Grep, Glob, Bash, Agent

Design an Interface

$ARGUMENTS

Generate 3+ radically different interface designs using parallel sub-agents, then compare. Based on "Design It Twice" from "A Philosophy of Software Design."

Usage

/design-an-interface [module or interface to design]

What This Command Does

1. Gathers requirements and constraints
2. Spawns 3+ parallel sub-agents with different design constraints
3. Presents each design with signatures, usage examples, and trade-offs
4. Compares on simplicity, depth, efficiency, and correctness
5. Synthesizes best elements into final recommendation

Process

1. Gather Requirements

Before designing, understand:

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

2. Generate Designs (Parallel Sub-Agents)

Spawn 3+ sub-agents simultaneously using Agent tool. Each gets a radically different constraint:

Agent	Constraint
Agent 1	Minimize method count — aim for 1-3 methods max
Agent 2	Maximize flexibility — support many use cases
Agent 3	Optimize for the most common case
Agent 4	Take inspiration from a specific paradigm/library

Each agent outputs:

1. Interface signature (types/methods)
2. Usage example (how caller uses it)
3. What this design hides internally
4. Trade-offs of this approach

3. Present Designs

Show each design sequentially so user can absorb each approach before comparison:

1. Interface signature — types, methods, params
2. Usage examples — how callers actually use it
3. What it hides — complexity kept internal

4. Compare Designs

Compare in prose (not tables) on:

Criterion	Description
Interface simplicity	Fewer methods, simpler params
General-purpose vs specialized	Flexibility vs focus
Implementation efficiency	Does shape allow efficient internals?
Depth	Small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
Ease of correct use	vs ease of misuse

5. Synthesize

Often the best design combines insights from multiple options. Give an opinionated recommendation. Ask:

• Which design best fits the primary use case?
• Any elements from other designs worth incorporating?

Visual Companion (Optional)

When upcoming design explorations will involve visual content (mockups, layout comparisons, architecture diagrams), offer the browser companion:

"Some of these interface designs might be easier to compare visually. I can show diagrams and side-by-side comparisons in a browser. Want to try it?"

This offer MUST be its own message. Do not combine with other questions. Wait for response.

If accepted, start the server and use it for visual comparisons only. Text/conceptual questions stay in terminal.

See ../write-a-prd/reference/visual-companion.md for details.

Anti-Patterns

• Don't let sub-agents produce similar designs — enforce radical difference
• Don't skip comparison — the value is in contrast
• Don't implement — this is purely about interface shape
• Don't evaluate based on implementation effort

READ-ONLY

This skill designs interfaces. It does NOT write implementation code.