design-an-interface

name	design-an-interface
description	Trigger: designing API, interface, hook, undecided on shape, want alternatives, which pattern to choose. 3 parallel designs: minimal, flexible, ergonomic — recommends one. Skip: implementation tasks.
author	Gonzalo Astudillo
version	1.0.0
date	"2026-04-27T00:00:00.000Z"
user-invocable	true

Design an Interface

The Principle

Your first idea is rarely the best. Before committing to a design, explore radically different alternatives. The goal is a deep module — a simple interface that conceals substantial complexity.

Shallow interface: many methods, little hidden = complexity leaks to callers. Deep module: few methods, much hidden = callers stay simple.

Hard Rules

• Never write implementation code before completing Step 5 (recommendation)
• Always generate exactly 3 designs — minimal, flexible, ergonomic — never fewer, never more
• Each design MUST have an opposing constraint that forces it away from the obvious solution
• Recommend exactly ONE design at the end — never leave the choice to the user
• Sub-agents run in parallel (Step 2) — never sequentially

When to Use

Use this skill after /shaping has defined what problem to solve and before implementing. It answers: given the problem is scoped, what should the contract look like?

/shaping  →  what to build (macro)
/design-an-interface  →  how the contract should look (micro)

Workflow

Step 1: Gather Requirements

Before generating alternatives, clarify:

• What problem does this interface solve?
• Who calls it? (other modules, external clients, tests)
• What operations must it support?
• What complexity should it hide internally?
• What must NOT leak through the interface?

Ask only what's missing — don't interview if the context is already clear.

Step 2: Launch 3 Sub-Agents in Parallel

Spawn three sub-agents simultaneously, each with a different constraint:

Sub-Agent A — Minimal Surface Constraint: minimize the number of methods/parameters. If in doubt, leave it out. Goal: find the smallest API that still solves the problem.

Sub-Agent B — Maximum Flexibility Constraint: make every behavior configurable and extensible. Goal: find the most adaptable API that anticipates future needs.

Sub-Agent C — Golden Path Optimization Constraint: optimize for the single most common use case. Make that case trivially easy, even if edge cases are harder. Goal: find the most ergonomic API for the 80% scenario.

Each sub-agent must produce:

1. The interface signature (types, method names, parameters)
2. A concrete usage example (2-3 lines of calling code)
3. What complexity it hides internally
4. What it deliberately does NOT support

Step 3: Present All Three Designs

Show each design side by side. For each:

• Signature
• Usage example
• Hidden complexity
• Limitations

Step 4: Compare on 4 Dimensions

Dimension	Design A	Design B	Design C
Simplicity
Generality
Implementation cost
Module depth

Step 5: Recommend

Choose one design (or synthesize the best elements) and explain:

• Why it wins on the most important dimension
• What tradeoffs you're accepting
• What you'd change if requirements shifted

Output Format

End with a single code block showing the recommended interface, ready to be used as the starting point for implementation.

Gotchas

• Generating 3 designs that are all slight variations of the same shape — force each agent to start from an opposing constraint, not the same mental model
• Recommending "it depends on the use case" instead of one design — always pick one, even if the reasoning is short
• Sub-agents running sequentially instead of in parallel — all 3 Agent calls must be in a single message
• Skipping Step 1 when context seems clear — missing a key caller or constraint produces designs that don't fit

Relationship with Other Skills

• Run /shaping first to define the problem scope
• Run /tdd after to implement with tests that verify the chosen interface
• Run /domain-model if the interface involves domain concepts that need precise language