starting-a-design-plan

Starting a Design Plan

Overview

Orchestrate the complete design workflow from initial idea to implementation-ready documentation through six structured phases: context gathering, clarification, definition of done, brainstorming, design documentation, and planning handoff.

Core principle: Progressive information gathering -> clear understanding -> creative exploration -> validated design -> documented plan.

Announce at start: "I'm using the starting-a-design-plan skill to guide us through the design process."

Quick Reference

| Phase | Key Activities | Output | |-------|---------------|--------| | 1. Context Gathering | Ask for freeform description, constraints, goals, URLs, files | Initial context bundle | | 2. Clarification | Invoke asking-clarifying-questions skill | Disambiguated requirements | | 3. Definition of Done | Synthesize and confirm deliverables before brainstorming | Confirmed success criteria | | 4. Brainstorming | Invoke brainstorming skill | Validated design (in conversation) | | 5. Design Documentation | Invoke writing-design-plans skill | Committed design document | | 6. Planning Handoff | Offer to invoke writing-plans skill | Implementation plan (optional) |

The Process

REQUIRED: Create task tracker at start

Use TaskCreate to create todos for each phase (or TodoWrite in older Claude Code versions):

• Phase 1: Context Gathering (initial information collected)
• (conditional) Read project design guidance (if .ed3d/design-plan-guidance.md exists)
• Phase 2: Clarification (requirements disambiguated)
• Phase 3: Definition of Done (deliverables confirmed)
• Phase 4: Brainstorming (design validated)
• Phase 5: Design Documentation (design written to docs/design-plans/)
• Phase 6: Planning Handoff (implementation plan offered/created)

Use TaskUpdate to mark each phase as in_progress when working on it, completed when finished (or TodoWrite in older versions).

Phase 1: Context Gathering

Never skip this phase. Even if the user provides detailed information, ask for anything missing.

Use TaskUpdate to mark Phase 1 as in_progress.

Ask the user to provide (freeform, not AskUserQuestion):

"I need some information to start the design process. Please provide what you have:

What are you designing?

• High-level description of what you want to build
• Goals or success criteria
• Any known constraints or requirements

Context materials (very helpful if available):

• URLs to relevant documentation, APIs, or examples
• File paths to existing code or specifications in this repository
• Any research you've already done

Project state:

• Are you starting fresh or extending existing functionality?
• Are there existing patterns in the codebase I should follow?
• Any architectural decisions already made?

Share whatever details you have. We'll clarify anything unclear in the next step."

Progressive prompting: If user already provided some of this information, acknowledge what you have and ask only for what's missing.

Example: "You mentioned OAuth2 integration. I have the high-level goal. To help design this effectively, I need:

• Any constraints (regulatory, existing auth system, etc.)
• URLs to the OAuth2 provider's documentation (if you have them)
• Whether this is for human users, service accounts, or both"

Mark Phase 1 as completed when you have initial context.

Between Phase 1 and Phase 2: Check for Project Guidance

Before clarification, check for project-specific design guidance.

Check if .ed3d/design-plan-guidance.md exists:

Use the Read tool to check if .ed3d/design-plan-guidance.md exists in the session's working directory.

If the file exists:

1. Use TaskCreate to add: "Read project design guidance from [absolute path to .ed3d/design-plan-guidance.md]"
2. Set this task as blocked by Phase 1 (Context Gathering)
3. Update Phase 2 (Clarification) to be blocked by this new task
4. Mark the task in_progress
5. Read the file and incorporate the guidance into your understanding
6. Mark the task completed
7. Proceed to Phase 2

If the file does not exist:

Proceed directly to Phase 2. Do not create a task or mention the missing file.

What project guidance provides:

• Domain-specific terminology to use in clarification
• Architectural constraints or preferences
• Technologies that are required, preferred, or forbidden
• Stakeholders and their priorities
• Project conventions that designs must follow

The guidance informs what questions you ask during clarification.

Phase 2: Clarification

Use TaskUpdate to mark Phase 2 as in_progress.

REQUIRED SUB-SKILL: Use ed3d-plan-and-execute:asking-clarifying-questions

Announce: "I'm using the asking-clarifying-questions skill to make sure I understand your requirements correctly."

The clarification skill will:

• Use subagents to try to disambiguate before raising questions to the user
• Disambiguate technical terms ("OAuth2" -> which flow?)
• Identify scope boundaries ("users" -> humans? services? both?)
• Clarify assumptions ("integrate with X" -> which version?)
• Understand constraints ("must use Y" -> why?)

Subagents used during clarification must not dispatch additional subagents.

Output: Clear understanding of what user means, ready to confirm Definition of Done.

Mark Phase 2 as completed when requirements are disambiguated.

Phase 3: Definition of Done

Before brainstorming the how, lock in the what. Brainstorming explores texture and approach — it assumes the goal is already clear.

Use TaskUpdate to mark Phase 3 as in_progress.

Synthesize the Definition of Done from context gathered so far:

From Phases 1-2 (Context Gathering and Clarification), you should be able to infer or extract:

• What the deliverables are (what gets built/changed)
• What success looks like (how we know it's done)
• What's explicitly out of scope

If the Definition of Done is clear:

State it back to the user and confirm using AskUserQuestion:

Question: "Before we explore approaches, let me confirm what success looks like:"
Options:
  - "Yes, that's right" (Definition of Done is accurate)
  - "Needs adjustment" (User will clarify what's missing or wrong)

Present the Definition of Done as a brief statement (2-4 sentences) covering:

• Primary deliverable(s)
• Success criteria
• Key exclusions (if any were discussed)

If the Definition of Done is unclear:

Ask targeted questions to nail it down. Use AskUserQuestion when there are discrete options, or open-ended questions when you need the user to describe their vision.

Examples of clarifying questions:

• "What's the primary deliverable here — is it [X] or [Y]?"
• "How will you know this is done? What would you test or demonstrate?"
• "You mentioned [feature]. Is that in scope for this design, or a future addition?"

Do not proceed to brainstorming until Definition of Done is confirmed.

Create Design Document Immediately After Confirmation

REQUIRED: Once the user confirms the Definition of Done, create the design document file immediately. This captures the DoD at full fidelity before brainstorming begins.

Step 1: Get Design Plan Name

The slug becomes part of all acceptance criteria identifiers (e.g., my-feature.AC1.1) and appears in test names. Ask the user to choose it explicitly.

Generate 2-3 suggested slugs based on the conversation context. Good slugs are:

• Lowercase with hyphens (no spaces, underscores, or special characters)
• Terse but unambiguous — prefer short forms that don't create confusion (e.g., authn not authentication, but not auth since that's ambiguous with authz)
• Recognizable months later

Use AskUserQuestion:

Question: "What should we call this design plan? The name becomes the prefix for all acceptance criteria (e.g., `{slug}.AC1.1`) and appears in test names.

If you have a ticketing system, you can use the ticket name (e.g., PROJ