Starting a Design Plan Skill

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:

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
Mark the task in_progress
Read the file and incorporate the guidance into your understanding
Mark the task completed
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-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

Research agents used during brainstorming must not dispatch additional subagents.

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

| Excuse | Reality | |--------|---------| | "User provided details, can skip context gathering" | Always run Phase 1. Ask for what's missing. | | "Requirements are clear, skip clarification" | Clarification prevents misunderstandings. Always run Phase 2. | | "I know what done looks like, skip confirmation" | Confirm Definition of Done explicitly. Always run Phase 3. | | "Simple idea, skip brainstorming" | Brainstorming explores alternatives. Always run Phase 4. | | "Design is in conversation, don't need documentation" | Documentation is contract with writing-implementation-plans. Always run Phase 5. | | "Can invoke implementation planning directly" | Must /clear first. Provide copy-then-clear workflow. | | "I can combine phases for efficiency" | Each phase has distinct purpose. Run all six. | | "User knows what they want, less structure needed" | Structure ensures nothing is missed. Follow all phases. |

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

Key Principles

| Principle | Application | |-----------|-------------| | Never skip brainstorming | Even with detailed specs, always run Phase 4 (may be shorter) | | Progressive prompting | Ask for less if user already provided some context | | Clarify before ideating | Phase 2 prevents building the wrong thing | | Lock in the goal before exploring | Phase 3 confirms what "done" means before brainstorming the how | | All brains in skills | This skill orchestrates; sub-skills contain domain expertise | | Task tracking | YOU MUST create todos with TaskCreate and update with TaskUpdate for all phases (or TodoWrite in older versions) | | Flexible progression | Go backward when needed to fill gaps |

Agent Skills: Starting a Design Plan

Install this agent skill to your local

Skill Files