starting-a-design-plan skill

---
name: starting-a-design-plan
description: Use when beginning any design process - orchestrates gathering context, clarifying requirements, brainstorming solutions, and documenting validated designs to create implementation-ready design documents
user-invocable: false
---

# 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]"
   - 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:**

```markdown
# [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-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 |