git:20260722.fcfda01 to git:20260919.b55f118

11 added, 7 removed. Audit A to A.

---

name: design-it-twice

- description: "Generates and compares at least two fundamentally different design alternatives on concrete criteria before committing. Use when the user asks to design something twice, or before committing to any significant design of classes, modules, APIs, or architecture. Not for judging strategic vs. tactical investment in existing code (use strategic-mindset) or whether a change degrades design (use code-evolution)."

+ description: "Generates and compares at least two fundamentally different design alternatives on concrete criteria before committing. Use when the user asks to design something twice, or before committing to any significant design of classes, modules, APIs, or architecture. Also use when asked how to structure or architect a feature, or when writing the design or alternatives section of an RFC, design doc, or ADR. Not for judging strategic vs. tactical investment in existing code (use strategic-mindset) or whether a change degrades design (use code-evolution)."

argument-hint: "[description of the design problem]"

allowed-tools: Read, Grep, Task

---

# Design It Twice

- When invoked with $ARGUMENTS, treat the argument as the design problem to explore. Do not assume a solution. Start from the problem statement and generate at least two fundamentally different approaches independently. If a design already exists in the conversation or codebase, dispatch the `clean-room-alternative` agent (see Isolation Mode below) rather than trying to produce a second attempt yourself — a design already sitting in your context contaminates anything you write next, no matter how deliberately you try to ignore it. Then compare all approaches on concrete criteria.

+ When invoked with $ARGUMENTS, treat the argument as the design problem to explore. Do not assume a solution. Start from the problem statement and generate at least two fundamentally different approaches independently. If the user or the codebase supplied a design, dispatch the `clean-room-alternative` agent (see Isolation Mode below) rather than trying to produce a second attempt yourself — a design already sitting in your context contaminates anything you write next, no matter how deliberately you try to ignore it. A design you drafted yourself while working on a fresh problem does not count as a supplied design: for a fresh problem, generate the alternatives directly. Then compare all approaches on concrete criteria.

- **This skill has two modes.** Before a design exists, use it to generate and compare alternatives directly. After a design exists, dispatch the isolated agent described below to produce an independent second attempt that isn't anchored to the first. Either way, the first idea is unlikely to produce the best design, not because the designer isn't smart, but because the problems are genuinely hard.

+ **This skill has two modes.** For a fresh problem, where the user supplied no design, generate and compare alternatives directly, using the forcing technique below to push past your first idea. When the user or the codebase supplied a design, dispatch the isolated agent described below to produce an independent second attempt that isn't anchored to the first. Either way, the first idea is unlikely to produce the best design, not because the designer isn't smart, but because the problems are genuinely hard.

## When to Apply

- Before committing to a class, module, or API design

- When choosing between architectural approaches

- When an interface feels awkward but "good enough"

- When writing a design document or RFC

- When you catch yourself thinking "this is obviously the right way"

## When NOT to Apply

- Trivial decisions with negligible consequences

- Well-established patterns where the design space is explored

- Bug fixes that don't change the interface

- Cost of the exercise should be proportional to cost of getting the design wrong

## The Procedure

1. **Generate at least two fundamentally different approaches**, not variations on one idea. If both share an interface shape, they're variations. Push until the second makes you uncomfortable.

- 2. **Compare the designs on concrete criteria:**

+ **In a design doc or RFC**, this still applies. Develop at least two alternatives to the same depth (interface, state ownership, data flow) before the doc commits to one. A full design followed by an "Alternatives considered" list of one-paragraph rejections is a single design, not a comparison. Keep the side-by-side comparison in the doc so reviewers can see why the chosen design won.

+ 2. **Check for convergence.** If two designs match on interface shape, state ownership, and decomposition, they are one design. Do not present them as two. Apply the pre-mortem from `references/pre-mortem-fallback.md` to that design to force a structural departure, then compare the result against it.

+ 3. **Compare the designs on concrete criteria:**

- **Caller ease-of-use**: Which requires less work from higher-level code? (primary criterion)

- **Interface simplicity**: Which is easier to learn and use?

- **Generality**: Which handles more use cases without special-casing?

- **Implementation complexity**: Which is easier to get right?

- **Performance characteristics**: Are there meaningful performance differences?

- 3. **Choose or synthesize**: Comparing two weak designs may reveal a shared weakness that points at a third, stronger design neither suggested directly. **When no alternative is attractive,** use the problems you identified to drive a new design. If both alternatives force callers to do extra work, that's a signal the abstraction level is wrong.

+ 4. **Choose or synthesize**: Comparing two weak designs may reveal a shared weakness that points at a third, stronger design neither suggested directly. **When no alternative is attractive,** use the problems you identified to drive a new design. If both alternatives force callers to do extra work, that's a signal the abstraction level is wrong.

### Applies at Multiple Levels

Use for interfaces first, then again for implementation (where simplicity and performance matter most), and again at system level (module decomposition, feature design). Different levels, different criteria, but always more than one option.

## Why It Works

When you only have one design, its strengths are invisible and its weaknesses look like inherent constraints. A second design breaks that illusion by making trade-offs visible. Documenting the alternatives you considered also prevents future maintainers from revisiting rejected or failed approaches.

Recording rejected alternatives and why they were rejected — in the design doc, commit message, or PR description — means a future agent invocation (which starts with an empty context window) gets the comparison for free instead of re-deriving it from scratch.

### The Smart People Trap

The first design generated anchors everything after it — once a finished design sits in context, it contaminates the comparison the same way a finished implementation contaminates a rewrite. Pushing past that anchor is what produces the stronger second design.

> "It isn't that you aren't smart; it's that the problems are really hard!" — John Ousterhout, _A Philosophy of Software Design_

Forcing technique: "Suppose you may not implement your first idea. What would be your second approach?" The second idea, when forced, is consistently better.

## Isolation Mode

- When a design already exists in the conversation or codebase, the second alternative should be generated in a clean-room context. Use the `clean-room-alternative` agent to produce the second design in isolation.

+ When the user or the codebase supplied a design, the second alternative should be generated in a clean-room context. Do not use isolation mode for a design you drafted yourself on a fresh problem. Use the `clean-room-alternative` agent to produce the second design in isolation.

#### Dispatch the agent with

1. The problem statement from $ARGUMENTS

2. Relevant file paths the agent should read for context

#### The agent receives

- The problem statement

- Access to the codebase via Read, Grep, Glob

#### The agent should NOT receive

- The first design

- Conversation history containing the first design

- Any indication of what approaches to avoid

- After the agent returns its design, compare both approaches using the criteria in "The Procedure" above. The value is in the comparison, not in either design alone.

+ After the agent returns its design, check it for convergence (step 2 of "The Procedure"), then compare both approaches using the criteria there. The value is in the comparison, not in either design alone.

### Fallback (No Agent Available)

If your runtime does not support agents, use the design pre-mortem technique from `references/pre-mortem-fallback.md` to force a structurally different alternative without clean-room isolation.

## Time Cost

Sketching and comparing two alternatives costs a small fraction of the tokens a full implementation consumes — and far less than the tokens spent debugging, then re-implementing, a flawed first design. The ratio holds: exploration is on the order of a few percent of implementation cost, with disproportionate return.

## Review Process

1. **Check for alternatives**: Was more than one genuinely different design considered? Was the reasoning for rejecting alternatives documented?

2. **Evaluate comparison quality**: Concrete criteria used, or gut feel?

3. **Look for shared weaknesses**: Do alternatives share a flaw pointing at a better design?

4. **Assess proportionality**: Depth of exploration proportional to decision's impact?

5. **Check for synthesis**: Could the best elements be combined?

Red flag signals for design comparison are cataloged in **red-flags** (No Alternatives Considered).