---
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](../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.