---

name: design-doc-creator description: Creates comprehensive Design Docs optimized for AI-driven development. Use when starting a new feature, documenting technical solutions, or before executing development tasks. Conducts iterative interviews to gather complete context, then generates structured documentation following a strict template.

Design Doc Creator Skill

Overview

This skill guides the creation of comprehensive Design Docs optimized for AI agents (especially Claude Code CLI) and human developers. It produces concise, information-dense documentation that serves as the "memory" and "guide" for development without hallucination.

When to Use This Skill

Use this skill when:

• Starting a new feature or module development
• Needing to document a technical solution before implementation
• Creating context for Claude Code to execute development tasks
• Requiring a structured approach to capture requirements and solution design

Workflow

Phase 1: Discovery (Interview)

The AI conducts an iterative interview to gather all necessary information:

1. Initial Scope Question

   • Ask: "What functionality are you documenting? Provide a brief description."

2. Iterative Deep Dive (2-3 questions per block)

   • Context & Purpose:

     • What problem does this solve?
     • Why is this being built now?
     • Who are the primary users/stakeholders?

   • Terminology & Concepts:

     • What specific terms or concepts need definition?
     • Are there domain-specific terms that require clarification?

   • Integrations & Dependencies:

     • What external APIs/services will be used?
     • What are the key endpoints/methods?
     • What authentication is required?

   • CRITICAL - Solution Phases:

     • What are the logical phases of implementation? (e.g., Setup, Backend, Infrastructure)
     • This grouping is essential for task organization

   • Detailed Solution:

     • For each phase, what specific tasks are needed?
     • What are the business rules for each task?
     • What is the input → processing → output for each task?

   • Data Flow:

     • What is the step-by-step flow from user action to system response?
     • What are the critical decision points?

3. Validation Before Generation

   • Before generating the document, confirm you have:
     • Clear context and purpose
     • All key terms defined
     • Integration details documented
     • Tasks grouped into logical phases
     • Detailed business rules for each task
     • Complete data flow mapped
   • Ask: "Is there any additional information needed before I generate the Design Doc?"

Phase 2: Generation (Documentation)

Generate the Design Doc using strictly this template:

Design Doc Template

Copy# [Feature Name] - Design Doc

## 1. Context
> [1-2 paragraph summary: WHAT is the feature and WHY it's being built]

## 2. Glossary
| Term | Description |
|:-----|:------------|
| [Term] | [Clear definition] |

## 3. Integrations and APIs
| API / Service | Usage Description | Key Methods/Endpoints |
|:--------------|:------------------|:----------------------|
| [e.g., Stripe /v1/customers] | [To create users] | [POST /create] |

## 4. Detailed Solution
*Group tasks logically (e.g., Setup, Client Integration, Subscriptions, Extras)*

| Phase | Task | Detailed Behavior Description (Business Rules) | Status |
|:------|:-----|:----------------------------------------------|:-------|
| **Setup** | Configure Credentials | Obtain API keys and save in environment variables. | `DEFINED` |
| **Client Integration** | Customer Creation | When registering user, create Customer in API X and save ID in database. | `DEFINED` |
| **[Category]** | [Task Name] | [Input → Processing → Output] | `UNDEFINED` |

## 5. Data Flow (Step-by-Step)
1. **[Actor]** initiates [Action]
2. **[System]** verifies [Condition]
3. **[System]** executes [Operation]
4. **[System]** returns [Result]
5. **[Actor]** receives [Feedback]

## 6. Technical Considerations
- Performance requirements
- Security considerations
- Error handling strategy
- Scalability concerns

## 7. Success Criteria
- [ ] [Measurable criterion 1]
- [ ] [Measurable criterion 2]
- [ ] [Measurable criterion 3]

Output Format

The skill should create a .md file in the /docs/features/[feature-name] folder with the naming convention: design-doc-[feature-name].md

Best Practices

1. Be Iterative: Don't rush to generate. Gather complete information first.

2. Focus on Behavior: In the Detailed Solution section, describe WHAT happens, not HOW to code it.

3. Group Intelligently: Tasks should be grouped by logical implementation phases, not by technical layers.

4. Be Specific: Avoid vague descriptions like "handle errors" → Instead: "If API returns 429, retry with exponential backoff (max 3 attempts)"

5. Think in Workflows: Data flow should read like a movie script - clear actors and actions.

6. Status Tracking: Use DEFINED, UNDEFINED, IN_PROGRESS, COMPLETED for task status.

Example Usage in Claude Code

Copy# Start the design doc creation process
User: "Create a design doc for user authentication with OAuth"

Claude Code: [Follows discovery phase with targeted questions]

# After gathering information
Claude Code: [Generates design-doc-oauth-authentication.md]

# User can then reference this in subsequent tasks
User: "Implement the tasks from the design doc in order"

Anti-Patterns to Avoid

❌ Generating the document without sufficient detail ❌ Mixing implementation details (code) with design decisions ❌ Creating tasks that are too granular (aim for 30min-2hr chunks) ❌ Forgetting to group tasks into logical phases ❌ Using vague business rules ("validate input" vs "validate email format: RFC 5322 compliant")

Skill Outputs

• Primary: A complete Design Doc markdown file
• Secondary: A clear understanding of the feature scope and implementation approach
• Tertiary: A ready-to-execute task list for Claude Code