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

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]"
   • Set this task as blocked by Phase 1 (Context Gathering)
   • Update Phase 2 (Clarification) to be blocked by this new task
2. Mark the task in_progress
3. Read the file and incorporate the guidance into your understanding
4. Mark the task completed
5. 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?)

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-1234)."

Options:
  - "[auto-generated-slug-1]" (e.g., "oauth2-svc-authn")
  - "[auto-generated-slug-2]" (e.g., "svc-authn")
  - "[auto-generated-slug-3]" (if meaningfully different)

If user selects "Other": They can provide any name. Normalize it:

• Ticket names (pattern: UPPERCASE-DIGITS, e.g., PROJ-1234): keep as-is
• Descriptive names: lowercase, hyphens for spaces, strip invalid characters (e.g., "My Cool Feature" → my-cool-feature)

Step 2: Create File

File location: docs/design-plans/YYYY-MM-DD-{slug}.md

Use today's date and the user-chosen slug.

Initial file contents:

# [Feature Name] Design

## Summary
<!-- TO BE GENERATED after body is written -->

## Definition of Done
[The confirmed Definition of Done - copy exactly as confirmed with user]

## Acceptance Criteria
<!-- TO BE GENERATED and validated before glossary -->

## Glossary
<!-- TO BE GENERATED after body is written -->

Why write immediately:

• Captures Definition of Done at peak resolution (right after user confirmation)
• Prevents fidelity loss during brainstorming conversation
• Creates working document that grows incrementally
• Acceptance Criteria, Summary, and Glossary filled in later by writing-design-plans skill

Mark Phase 3 as completed when user confirms the Definition of Done AND the file is created.

Phase 4: Brainstorming

With clear understanding from Phases 1-3, explore design alternatives and validate the approach.

Use TaskUpdate to mark Phase 4 as in_progress.

REQUIRED SUB-SKILL: Use ed3d-plan-and-execute:brainstorming

Announce: "I'm using the brainstorming skill to explore design alternatives and validate the approach."

Pass context to brainstorming:

• Information gathered in Phase 1
• Clarifications from Phase 2
• Confirmed Definition of Done from Phase 3
• This reduces Phase 1 of brainstorming (Understanding) since much is already known

The brainstorming skill will:

• Complete any remaining understanding gaps (Phase 1)
• Propose 2-3 architectural approaches (Phase 2)
• Present design incrementally for validation (Phase 3)
• Use research agents for codebase patterns and external knowledge

Output: Validated design held in conversation context.

Mark Phase 4 as completed when design is validated.

Phase 5: Design Documentation

Append the validated design to the document created in Phase 3.

Use TaskUpdate to mark Phase 5 as in_progress.

REQUIRED SUB-SKILL: Use ed3d-plan-and-execute:writing-design-plans

Announce: "I'm using the writing-design-plans skill to complete the design document."

Important: The design document already exists from Phase 3 with:

• Title
• Summary placeholder
• Confirmed Definition of Done
• Acceptance Criteria placeholder
• Glossary placeholder

The writing-design-plans skill will:

• Append body sections (Architecture, Existing Patterns, Implementation Phases, Additional Considerations) to the existing file
• Structure with implementation phases (<=8 recommended)
  • DO NOT pad out phases in order to reach the number of 8. 8 is the maximum, not the target.
• Document existing patterns followed
• Generate Acceptance Criteria (success + failure cases for each DoD item), get human validation
• Generate Summary and Glossary to replace placeholders
• Commit to git

Output: Committed design document ready for implementation planning.

Mark Phase 5 as completed when design document is committed.

Phase 6: Planning Handoff

After design is documented, guide user to create implementation plan in fresh context.

Use TaskUpdate to mark Phase 6 as in_progress.

Do NOT create implementation plan directly. The user needs to /clear context first.

Announce design completion and provide next steps:

Design complete! Design document committed to `docs/design-plans/[filename]`.

Ready to create the implementation plan? This requires fresh context to work effectively.

**IMPORTANT: Copy the command below BEFORE running /clear (it will erase this conversation).**

(1) Copy this command now:

/ed3d-ed3d-plan-and-execute:start-implementation-plan @docs/design-plans/[full-filename].md .

(the `.` at the end is necessary or else Claude Code will eat the command and do the wrong thing.)

(2) Clear your context:

/clear

(3) Paste and run the copied command.

The start-implementation-plan command will create detailed tasks, set up a branch, and prepare for execution.

Why /clear instead of continuing:

• Implementation planning needs fresh context for codebase investigation
• Long conversations accumulate context that degrades quality
• /clear gives the next phase a clean slate

Mark Phase 6 as completed after providing instructions.

When to Revisit Earlier Phases

You can and should go backward when:

• Phase 2 reveals fundamental gaps -> Return to Phase 1
• Phase 3 reveals unclear deliverables -> Return to Phase 2 for more clarification
• Phase 4 uncovers new constraints -> Return to Phase 1, 2, or 3
• User questions approach during Phase 4 -> Return to Phase 2
• Phase 4 changes the Definition of Done -> Return to Phase 3 to reconfirm
• Design documentation reveals missing details -> Return to Phase 4

Don't force forward linearly when going backward gives better results.

Common Rationalizations - STOP

All of these mean: STOP. Run all six phases in order.

Key Principles