vac-optimizer/.agents/skills/codebase-design/DESIGN-IT-TWICE.md

Design It Twice

When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.

Uses the vocabulary in SKILL.md — module, interface, seam, adapter, leverage.

Process

1. Frame the problem space

Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:

• The constraints any new interface would need to satisfy
• The dependencies it would rely on, and which category they fall into (see DEEPENING.md)
• A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete

Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.

2. Spawn sub-agents

Honor the requested number of alternatives; two is a useful default. Use independent subagents through the available delegation tool when useful and within available slots, or compare directly when delegation is unavailable. Each option should explore a meaningfully different trade-off for the same requirements.

Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from DEEPENING.md, what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:

• One option can optimize for the primary caller's workflow.
• Another can emphasize explicit state transitions or failure handling.
• Add a dependency-focused option only when that is an actual design question; do not invent flexibility, adapters, or a target method count.

Include both SKILL.md vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.

Each sub-agent outputs:

1. Interface (types, methods, params — plus invariants, ordering, error modes)
2. Usage example showing how callers use it
3. What the implementation hides behind the seam
4. Dependency strategy and adapters (see DEEPENING.md)
5. Trade-offs — where leverage is high, where it's thin

3. Present and compare

Use the requested or clearest concise format. Contrast depth (leverage at the interface), locality (where change concentrates), seam placement, implementation effort, and risk.

After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.