Polyflow Design Interface

PolyFlow: 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 polyflow 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 ."

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 polyflow-writing-plans + polyflow-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 → polyflow-writing-plans (the plan implements the design)
• Design reveals architecture concerns → polyflow-improve-architecture first
• New domain terms emerged → polyflow-glossary to update CONTEXT.md