/design

Design: Structured Feature Design

A structured way to plan complex features before implementing. Works through: Problem → Options → Solution → Stories → Finalize.

The result is a Record (markdown file) that documents design decisions and breaks work into implementable stories.

Usage

/design "Feature name"     # Start new design
/design --continue         # Resume incomplete design
/design --review           # Get feedback on current design (requires comprehensive-review)

When to Use /design vs /todo

| Use /design when... | Use /todo when... | |---------------------|-------------------| | Feature has multiple parts | Just need a reminder | | Unsure how to implement | Quick idea for later | | Need to evaluate options | Simple task | | Architecture decision | - |

Tasks

Prerequisites

• If no project CLAUDE.md found: Tell user to run `/init-project` first
• If no `docs/records/` directory: Create it

Handle Arguments

**No arguments:** 1. Check for incomplete designs (Records with Status: "Designing") 2. If found: Show state summary, offer to resume (see "Resume Design Workflow") 3. If none: Ask "What feature do you want to design?"

**With feature name:** 1. Check if a Record for this feature already exists (search by title) 2. If found with Status "Designing": Ask "Resume existing design?" or "Start fresh?" 3. If found with Status "Designed/In Progress/Done": Ask "Feature already has Record [NNN]. Create new design anyway?" 4. Start new design workflow for the given feature

**--continue flag:** 1. Find incomplete designs (Records with Status: "Designing") 2. If multiple found: Show list, ask "Which design to continue?" 3. If single found: Show state summary, resume from current step 4. If none: "No incomplete design found. Start new with /design 'feature name'"

See "Resume Design Workflow" section below for details.

**--review flag:** 1. Find current design (active session or incomplete Record) 2. If multiple incomplete designs: Ask "Which design to review?" with list 3. If no design found: "No design to review. Start with /design 'feature name'" 4. If comprehensive-review plugin not installed: "Install comprehensive-review plugin for design reviews: /claude-code-setup → External Plugins" 5. If plugin installed: Invoke review agent (see Review Agent section below) 6. Show feedback to user (do not store in Record) 7. After review: Prompt with explicit next step (see After Review section)

---

Review Agent Integration

When `/design --review` is invoked, use the `comprehensive-review:architect-review` agent.

Finding the Design to Review

1. If in active design session: Review current Record 2. If multiple incomplete designs exist: Ask user which one to review 3. If single incomplete design: Review that Record 4. If no design found: "No design to review. Start with `/design 'feature name'`"

Determine Current Step

Check which sections exist in the Record (see "Step Inference for Resume" in State Tracking section for full logic):

| Sections Present | Phase | Next Step | |------------------|-------|-----------| | Problem only | Early | Step 2: Options | | Problem + Options + Decision | Mid | Step 3: Solution | | Problem + Solution (no Options) | Mid | Step 4: Stories (Options skipped) | | Problem + Solution + Stories | Late | Step 5: Finalize |

Review Prompt

Pass this context to the review agent:

Review this design record for [Feature Name].

Current state: [Phase] - [List completed sections]
Next step: Step N ([Step Name])
Remaining: [List remaining steps]
Tech Stack: [From project CLAUDE.md]

Record content:
[Full Record content]

Evaluate:
1. Problem clarity - Is the problem well-defined? Is the "why" clear?
2. Options analysis - Are alternatives properly considered? (if applicable)
3. Solution completeness - Does the solution address the problem?
4. Story quality:
   - Are stories independently implementable?
   - Are acceptance criteria clear and testable?
   - Are stories ordered by value and risk?
   - Any hidden dependencies between stories?
5. Architecture & design - Are patterns appropriate? Tech stack alignment?
6. Missing considerations - Security, performance, error handling, edge cases?

Focus feedback on completed sections. For in-progress sections, suggest improvements.
Be actionable: "Consider adding..." not "You forgot..."
Skip praise; focus on what can be improved.

After Review

Display feedback, then prompt with explicit next step:

Review complete. Feedback is NOT stored in the Record.

Current position: Step [N] ([Step Name])
Next: Step [N+1] ([Next Step Name])

Ready to continue?
[Yes] → Continue to Step [N+1]
[No]  → Save and exit (resume with `/design --continue`)

**If Yes:** Resume with the next step question (e.g., "Let's define the solution...") **If No:** Confirm save: "Design saved as docs/records/[NNN]-[slug].md. Resume anytime with `/design --continue`"

Error Handling

If review agent fails: 1. Show: "Review could not be completed: [error]" 2. Prompt: "Continue design without review? [Yes / No]"

---

Workflow: 5 Steps

The Record is created after Step 1 and updated after each subsequent step. User sees progress incrementally.

Step 1: Problem

Ask the user:

Let's design: [Feature Name]

First, let's understand the problem.
- What problem are we solving?
- Why does it need to be solved?
- What happens if we do nothing?

Wait for user response. Then:

1. **Create Record immediately** with next available number in `docs/records/` 2. Write Problem section to Record 3. Set Status: "Designing" 4. Confirm to user: "Record [NNN] created. Problem captured."

Step 2: Options (Conditional)

Assess if multiple approaches exist:

**If multiple viable approaches:** Ask the user:

What approaches have you considered? Let's evaluate options.

For each option, we'll note:
- Approach description
- Pros
- Cons

Discuss options with user. Then: 1. Update Record with Opti