Evanflow Design Interface

---
name: evanflow-design-interface
description: Design a module's interface using parallel sub-agents producing radically different designs ("design it twice"). Compare on depth, simplicity, and efficiency. Embedded grill on the synthesized choice. Use when designing a new API, exploring interface options, or deciding the shape of a refactor before writing code.
---

# EvanFlow: Design an Interface


Source principle: "Design It Twice" from John Ousterhout's *A Philosophy of Software Design*. Your first idea is unlikely to be the best. Generate radically different designs, compare, synthesize.

## Vocabulary

See `evanflow` meta-skill. Key terms: **interface**, **depth**, **module**, **adapter**.

## When to Use

- Designing a new API surface (tRPC router, service interface, public function set)
- Refactor changes a public interface — design before implementing
- Stuck on the shape of a module
- The team disagrees on the right interface

## The Flow

### 1. Gather Requirements

- What problem does this module solve?
- Who are the callers? (other modules, external users, tests)
- Key operations
- Constraints (performance, compatibility, existing project patterns from `CONTEXT.md`)
- What should be hidden vs. exposed

### 2. Spawn Parallel Sub-Agents (Design It Twice — actually 3+)

Dispatch 3+ Explore or general-purpose agents simultaneously (single message, multiple Agent tool calls). Each gets a **radically different** 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 (specify what that is)."
- **(Optional) Agent 4:** "Take inspiration from <specific paradigm or library>."

Each returns:

1. Interface signature (types, methods, params)
2. Usage example (how the caller actually uses it)
3. What the design hides internally
4. Trade-offs

### 3. Present Designs Sequentially

Show each design separately so the user can absorb each before comparison. No tables yet — let each design stand on its own.

### 4. Compare

After all designs are shown, compare on:

- **Interface simplicity**: fewer methods, simpler params
- **General-purpose vs. specialized**: flexibility vs. focus
- **Implementation efficiency**: does the shape allow efficient internals or force awkward ones?
- **Depth**: small interface hiding significant complexity (good) vs. large interface with thin implementation (bad)
- **Ease of correct use** vs. **ease of misuse**

Discuss in prose. Highlight where designs diverge most.

### 5. Synthesize

Often the best design combines insights from multiple options. Ask:

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

### 6. Embedded Grill on the Synthesis

Before committing to the design:

- "What's the simplest way a caller could misuse this?"
- "What test would force this interface to change unnecessarily? Does that test exist or would we write it?"
- "Is the interface still simple after we incorporate the borrowed elements, or did the synthesis bloat it?"
- "Apply the deletion test to internal helper modules implied by this design."

## Hard Rules

- **Don't let sub-agents converge.** Enforce radical difference. If agents return similar designs, re-spawn with sharper constraints.
- **Don't skip comparison.** The value is in the contrast.
- **Don't implement.** This skill is purely about interface shape. Implementation goes through `evanflow-writing-plans` + `evanflow-tdd`.
- **Don't evaluate based on implementation effort.** Evaluate on interface quality.
- **Never auto-commit.** Even a design doc gets staged, not committed.

## Hand-offs

- Design chosen → `evanflow-writing-plans` (the plan implements the design)
- Design reveals architecture concerns → `evanflow-improve-architecture` first
- New domain terms emerged → `evanflow-glossary` to update `CONTEXT.md`