design-first

# Design-First (Progressive Design Facilitation)

## The 5 Levels

### Level 1: Capabilities (The "What")

**Purpose**: Confirm scope. Surface the user-facing outcomes the system must deliver. Shared vocabulary check — ensure the human and the AI are talking about the same feature with the same boundaries.

**Output format**: Numbered list of user-facing capabilities, max 5. Each capability is a plain-language outcome, not an implementation detail.

**Boundary**: No components, no architecture, no technical detail. If a capability mentions a specific technology, class, or data structure, it belongs at a later level. This level answers only "what does the user get?"

**Checkpoint**: "Does this Level 1 (Capabilities) look correct? Should I proceed to Level 2 (Components)?"

### Level 2: Components (The "Who")

**Purpose**: Identify the building blocks. What major pieces does the system have, and what is each one responsible for?

**Output format**: 3-5 components, each with a single responsibility and a one-line description. Include an ASCII or Mermaid diagram showing how they relate. Note integration points with existing infrastructure.

**Boundary**: No data flow, no sequence of operations, no interaction detail. Describe each component by what it *is* and what it *owns* — not how it communicates with others. If you find yourself writing "A sends X to B", that belongs at Level 3.

**Checkpoint**: "Does this Level 2 (Components) look correct? Should I proceed to Level 3 (Interactions)?"

### Level 3: Interactions (The "How They Talk")

**Purpose**: Define the data flow between components. How do the building blocks communicate to deliver the capabilities?

**Output format**: A sequence diagram (ASCII or Mermaid) or a numbered flow showing the order of operations. For each interaction, describe WHAT data passes between components. See `./references/methodology-detail.md` for notation guidance.

**Boundary**: No function signatures, no type definitions, no implementation detail. Focus on what passes between components, not how each component processes internally. If you are defining method parameters or return types, that belongs at Level 4.

**Checkpoint**: "Does this Level 3 (Interactions) look correct? Should I proceed to Level 4 (Contracts)?"

### Level 4: Contracts (The "Interface Definitions")

**Purpose**: Define the interfaces, method signatures, and type definitions that formalize the interactions. This is the handoff artifact — the specification that implementation is built against.

**Output format**: Typed interfaces, method signatures, type definitions in a language-appropriate format (TypeScript interfaces, Java interfaces, Python protocols, etc.). Use the project's primary language; if ambiguous, ask before writing contracts. No function bodies — signatures and types only. Include error/failure types where interactions can fail. See `./references/methodology-detail.md` for interface definition patterns.

**Boundary**: No implementation logic. If a function body appears, it belongs at Level 5. Contracts reflect the design agreed at Levels 1-3, nothing more — no utility functions, helper methods, or convenience wrappers that are not part of the design. Every Level 3 interaction must map to at least one interface or type; no new interactions may appear here that were not agreed at Level 3.

**Checkpoint**: "Does this Level 4 (Contracts) look correct? Should I proceed to Level 5 (Implementation)?"

### Level 5: Implementation (The "Code")

**Purpose**: Write code. Implement against the agreed contracts, within the agreed component boundaries, following the agreed interaction patterns.

**Output format**: Working code that fulfills the contracts defined at Level 4, each component implemented within its agreed boundary. The implementation is reviewable against the design: each component checked against its Level 2 description, each interaction against its Level 3 flow, each interface against its Level 4 contract.

**STOP:** Only after Level 4 is explicitly approved. Implementation follows the design; it must not introduce new components, new interactions, or new contracts that were not agreed upon.

## The Zero Implementation Rule

**No code until the design is agreed.**

**STOP:** If you catch yourself writing function bodies before Level 5 is approved, return to the current design level and present only the output appropriate to that level.

## Complexity Calibration

| Task Complexity | Start At | Example |
|---|---|---|
| Simple utility | Level 4 (Contracts) | Date formatter, string helper |
| Single component | Level 2 (Components) | Validation service, API endpoint |
| Multi-component feature | Level 1 (Capabilities) | Notification system, payment flow |
| New system integration | Level 1 + deep Level 3 | Third-party API, event pipeline |

## Entry Assessment

Before producing the first level output, state the entry level and rationale:

"Based on [complexity signal], I'll start at Level [N] ([name]). Earlier levels are implicitly agreed — [brief statement of what's assumed]. Want to start here or go broader?"

Wait for confirmation before producing the first level output. If the user disagrees, adjust the entry point.

## Level Completion Protocol

At the end of each level:

1. Present the level output in the format specified for that level (numbered list, diagram, sequence flow, or interfaces).
2. Self-check: is this simpler than it could be? If a simpler alternative exists, present it alongside: "I have a simpler option — [alternative]. Which do you prefer?"
3. Ask the gating question: "Does this Level [N] look correct? Should I proceed to Level [N+1]?"
4. **STOP:** Wait for explicit approval. Do not advance on silence or ambiguity.
5. If the user redirects, corrects, or raises concerns, revise the current level. Do not advance until the revision is approved.

**Level 5 exit**: there is no Level 6 — at Level 5 the protocol ends after step 2. Present the implementation for