starting-a-design-plan

What this skill does

# 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")