Invoked helper skill for unresolved module boundaries, usually called from /write-a-prd. Use to compare multiple interface shapes for a module or component when caller ergonomics and surface area are still unclear. Not for API contract review or already-settled designs.
Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
This is an invoked helper skill. It normally runs from /write-a-prd when a module boundary is still unresolved, and it can also support refactor or architecture work when interface tradeoffs are the main uncertainty.
Use it when the open question is the shape of a module interface: method count, surface area, depth, caller ergonomics, or evolvability.
Do not use it when the real uncertainty is the API contract itself — that belongs in /api-design-review — or when the work is already clear enough to keep shaping or implementing without a design fork.
Before designing, understand:
Ask: "What does this module need to do? Who will use it?"
Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a radically different approach.
Prompt template for each sub-agent:
Design an interface for: [module description]
Requirements: [gathered requirements]
Constraints for this design: [assign a different constraint to each agent]
- 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 [specific paradigm/library]"
Output format:
1. Interface signature (types/methods)
2. Usage example (how caller uses it)
3. What this design hides internally
4. Trade-offs of this approach
Show each design with:
Present designs sequentially so user can absorb each approach before comparison.
After showing all designs, compare them on:
Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
Often the best design combines insights from multiple options. Ask one question at a time:
From "A Philosophy of Software Design":
Interface simplicity: Fewer methods, simpler params = easier to learn and use correctly.
General-purpose: Can handle future use cases without changes. But beware over-generalization.
Implementation efficiency: Does interface shape allow efficient implementation? Or force awkward internals?
Depth: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
Evolvability: Prefer interfaces that can absorb likely future change without forcing broad consumer breakage. If failure modes or versioning pressure are already obvious, evaluate them as part of the design rather than as an afterthought.
/write-a-prd, or occasionally refactor and architecture side-route skills