Design Plan

---
description: Interactive design document creation from unstructured planning with user confirmation at each stage
allowed-tools: [
  "Bash(find:*)",
  "Bash(ls:*)", 
  "Bash(grep:*)",
  "Bash(tree:*)",
  "Read",
  "Write",
  "Edit",
  "web_search",
  "web_fetch"
]
argument-hint: "[optional focus: 'feature-name'|'system-area'|'all']"
---

## Context

This command creates verified design documents through an interactive, iterative process:
1. **Analyze** - Understand scattered planning materials and current project state
2. **Confirm Direction** - Align on design scope and approach with user
3. **Verify Context** - Ensure technical documentation is available
4. **Generate Design** - Create workable design document for implementation

**Critical Principle:** User confirmation required before advancing to next stage. Iterate until alignment achieved.

---

## Stage 1: Discovery & Analysis

### Task
Explore and understand the current state without making assumptions.

### Process

**1.1 Scan Planning Directory**
```bash
# Discover everything in planning/
find planning/ -type f
tree planning/ -L 3

What to look for:

• Notes, brainstorms, ideas (*.md, *.txt, *.html)
• Visual materials (*.svg, *.png, diagrams)
• Code snippets, pseudocode, draft implementations
• Any structure (folders, naming patterns) or lack thereof
• Dates, versions, related materials

1.2 Scan Design Directory

# Check existing designs
find design/ -type f 2>/dev/null || echo "No design directory"
ls -lt design/ 2>/dev/null

What to look for:

• Previous design documents
• Implemented vs. unimplemented designs
• Related areas that might be affected
• Design patterns or structure to maintain

1.3 Scan Context Directory

# Check available context
find context/ -type f 2>/dev/null || echo "No context directory"
tree context/ -L 2

What to look for:

• Package documentation available
• API references present
• Syntax guides
• Framework documentation
• Gaps that might be needed

1.4 Quick Repository Scan (if relevant)

# Understand current implementation state
find src/ -name "*.py" -o -name "*.js" -o -name "*.ts" 2>/dev/null | head -20
ls -la *.md 2>/dev/null

What to look for:

• Current project structure
• Implemented features
• Coding patterns in use
• Configuration files

Output to User

Present findings as a structured summary:

📊 DISCOVERY ANALYSIS

====================
PLANNING MATERIALS FOUND
====================

Structured Documents (if any):
- planning/[file].md - [brief description of content]
- planning/[file].txt - [brief description]

Scattered Notes/Ideas:
- planning/notes/[files] - [themes identified]
- planning/[random-file] - [content type]

Visual Materials:
- planning/diagrams/[files] - [what they show]
- planning/[image].svg - [subject]

Code/Implementation Drafts:
- planning/draft-[name] - [what it implements]
- planning/[snippet].py - [functionality]

Key Themes Identified:
1. [Theme/Feature Area] - Found in: [files]
2. [Theme/Feature Area] - Found in: [files]
3. [Open questions/gaps]

====================
CURRENT DESIGN STATE
====================

Existing Design Documents:
- design/[file].md - [status: implemented/partial/unknown]
- [No existing designs] OR [List designs]

Design Patterns Observed:
- [Pattern/structure if identifiable]
- [None identified] OR [List]

====================
PROJECT CONTEXT
====================

Available Technical Context:
- context/packages/ - [X] files: [list key packages]
- context/apis/ - [X] files: [list]
- context/syntax/ - [X] files: [list]
- [Missing directory] - Not present

Current Implementation:
- Project structure: [language/framework if identifiable]
- Key directories: [src/, lib/, etc.]
- Configuration: [files found]

====================
INTERPRETATION
====================

What I think you're trying to build:
[High-level interpretation of the planning materials]

Scope appears to be:
[ ] Small feature addition
[ ] New system/module
[ ] Major refactor/redesign
[ ] Full project
[ ] Unclear - need clarification

Related existing designs that might be affected:
- [design file] - [relationship]
- None identified

====================
⚠️  AMBIGUITIES & QUESTIONS
====================

I'm uncertain about:
1. [Question about scope]
2. [Question about priorities]
3. [Conflicting information in planning]
4. [Missing information]

User Confirmation Required

Ask user:

Before proceeding, I need your input:

1. Is my interpretation of the planning materials correct?
   - What did I miss or misunderstand?
   - What's not relevant and should be ignored?

2. What is the actual scope of this design work?
   - Specific feature: [user describes]
   - System area: [user describes]
   - Full project: [user describes]

3. Are there existing designs I should maintain consistency with?
   - Which design documents matter?
   - What patterns/decisions must be preserved?

4. What's the priority/focus?
   - What must be in this design?
   - What can be deferred?

Please correct my understanding or confirm I can proceed to planning.

Iteration:

• If user provides corrections → update analysis → re-present → confirm
• If user clarifies scope → adjust interpretation → re-present → confirm
• Only proceed when user explicitly confirms: "Yes, proceed to Stage 2"

---

Stage 2: Design Direction & Scope Definition

Task

Define what design document(s) to create and what they should contain.

Process

2.1 Based on confirmed understanding from Stage 1, propose design approach:

📋 PROPOSED DESIGN APPROACH

====================
DESIGN DOCUMENT(S) TO CREATE
====================

Primary Design Document:
design/[PROPOSED-NAME].md

Purpose:
[What this design will specify]

Scope:
[What will be included in this design]

Structure (proposed):
1. Overview
2. [Section based on content]
3. [Section based on content]
4. [Section based on content]
5. Implementation Notes
6. Integration