design-first

# Design-First (Progressive Design Facilitation)

## The Problem

AI jump requirement→implementation, make all design decision silent. Result: you review code while evaluate scope, architecture, integration, contracts, quality -- all tangled. Catch scope mismatch in 2-min design talk way cheaper than find buried in 400 lines generated code.

Solution: rebuild whiteboard talk human pairs do natural -- progressive design levels before code.

## The 5 Levels

Five levels, abstract→concrete. Each level surface decision category that otherwise buried in generated code.

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

**Purpose**: Confirm scope. Surface user-facing outcomes system need deliver. Shared vocabulary check -- ensure human and AI talk same feature, same boundaries.

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

**Boundary**: No components, no architecture, no technical detail. If capability mention specific technology, class, or data structure -- belong later level. This level answer only "what user get?"

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

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

**Purpose**: Identify building blocks. What major pieces system, what each one responsible for?

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

**Boundary**: No data flow, no sequence operations, no interaction detail. Each component described by what it *is* and what it *owns* -- not how communicate with others. If write "A sends X to B" -- belong 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 data flow between components. How building blocks communicate deliver capabilities?

**Output format**: Sequence diagram (ASCII or Mermaid) or numbered flow showing order 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 what passes between components, not how each component process internally. If define method parameters or return types -- belong 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 interfaces, method signatures, type definitions that formalize interactions. Handoff artifact -- spec that implementation built against.

**Output format**: Typed interfaces, method signatures, type definitions. 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 function body appear -- belong Level 5. Contracts reflect design agreed Levels 1-3, nothing more. Utility functions, helper methods, convenience wrappers not in design not belong here. Every Level 3 interaction must map to at least one interface or type; no new interactions may appear here that weren't 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 agreed contracts, within agreed component boundaries, following agreed interaction patterns.

**Output format**: Working code fulfill contracts defined Level 4. Each component implemented within agreed boundary. Implementation reviewable against design -- reviewer check each component against Level 2 description, each interaction against Level 3 flow, each interface against Level 4 contract.

**Boundary**: Only after Level 4 explicitly approved. Implementation follow design; not introduce new components, new interactions, new contracts not agreed upon.

## The Zero Implementation Rule

Most critical discipline: **no code until design agreed.**

If catch self writing function bodies before Level 5 approved -- STOP. Return current design level, present only output appropriate that level.

Rule exist because AI training optimize for produce tangible output quick, means AI constantly try collapse levels -- offer component diagrams with code already written, or propose contracts with implementations attached. Discipline staying current abstraction level protect working memory from premature detail, keep conversation focused on decision category being made.

Simplest version entire methodology: no code until design agreed. Everything else follow from there.

## Complexity Calibration

Not every task need all five levels. Framework scale to complexity work -- tool for manage complexity, not ritual apply uniform.

| 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 |

When start later level, earlier levels implicitly agreed -- scope and components obvious enough not need explicit alignment.

## Entry Assessment

Before producing 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 g