Phase 1 — Design

What we're going to build and why.

🎯 Goal

Capture the problem being solved, what will be built to solve it, and why it matters — before discussing how.

The intent is to keep these decisions recorded and auditable later. In 6 months, when someone asks "why does this feature exist?", the answer is in DESIGN.md.

📋 What goes into DESIGN.md

1. Context / Problem

Why does this feature need to exist? What pain are we solving?

Don't confuse it with the solution. If you already know the solution, ask: "What problem does this solution solve?". Keep going up until you reach the root problem.

2. Success criteria

How will we know it worked? In testable metrics.

Bad: "the feature should be fast"
Good: "the POST /auth/login endpoint responds in < 200ms p95 with 100 concurrent req/s"

3. Constraints

What do we need to respect?

• Technical: mandatory stack, existing integrations, performance
• Business: deadline, regulation, cost
• Team: hard deadline, dependencies on other squads

4. Non-goals

What is explicitly out of scope?

The most underrated part of Design. Listing non-goals removes ambiguity later.

E.g.: "Social login (Google, Apple) is NOT in this phase. It will be a separate feature."

5. Personas and scenarios (if applicable)

Who uses it? In what context?

User stories in the "As an X, I want Y, so that Z" format work well.

6. Assumptions

What are we assuming?

Listing assumptions makes risk explicit. If an assumption turns out to be false, the project may pivot.

🤖 How the AI assists in this phase

The AI is maieutic — it helps you make explicit what you already know but haven't articulated. Good AI in the Design phase:

• ✅ Asks questions to remove ambiguities
• ✅ Suggests edge cases you didn't think of
• ✅ Asks for more specific criteria when you were vague
• ✅ Lists assumptions you're implicitly making

What the AI should NOT do here:

• ❌ Propose a solution / architecture
• ❌ Write example code
• ❌ Suggest specific libraries / frameworks
• ❌ Discuss technical trade-offs

All of that is Architect. If the AI insists on going there, you redirect it.

🚀 How to trigger it (Cursor)

/generate-design "I want to add JWT authentication to the API. Users log in with email/password, receive a 1h token and a 7-day refresh token. I need this to unblock the favorites feature that's waiting on it."

The AI will generate DARE/DESIGN.md with structured sections + questions in comments (<!-- ... -->) where it needs more info.

You answer inline, refine, and when you're satisfied, you approve it explicitly by removing the questions and marking the doc as ready.

✅ "Design is ready" criteria

Before moving on to Architect, validate:

• Problem described without mentioning a solution
• Success criteria are testable (with numbers)
• Constraints listed
• Non-goals explicit
• Assumptions recorded
• Another person (or you the next day) would understand the document without additional context

🚫 Common anti-patterns

"DESIGN.md with pseudocode"

You're already in Architect. Go back. Delete the implementation. Focus on the what/why.

"1-line DESIGN.md"

"Add JWT login" is not a design — it's a title. If it took less than 10 min to write, it's probably shallow.

"30-page DESIGN.md"

If it got too long, the scope is too big. Break it into 3-5 smaller designs.

"Approve and never look again"

DESIGN.md is alive throughout the project. If you discover a new requirement in the Architect or Execute phase, go back to DESIGN.md and update it. Don't cram a hack into the implementation.

📂 Templates

• templates/DESIGN-template.md (in the root of the universal templates — but each implementation has its own copy)

🔗 Next

Phase 2: Architect →