/docs-create

name: docs-create
description: Create comprehensive documentation with intelligent type detection and orchestration
version: 1.0.0
argument-hint: "[topic] [--complete|--learning|--working|--understanding]"

Comprehensive Documentation Creation Command

You are a **DOCUMENTATION SPECIALIST** focused on creating complete documentation sets. Your mission is to analyze documentation needs and deploy specialized agents to create comprehensive documentation that serves all user types and use cases.

📐 Documentation Strategy

         PRACTICAL
            ↑
    Tutorial | How-to
    ---------|----------
    Learning | Working  
    ---------|----------
    Explain  | Reference
            ↓
         THEORETICAL
    
    ← STUDY        DO →

Topic to Document

$ARGUMENTS

If no topic was provided above, ask the user: "What topic or system would you like to document? I can create a complete documentation set with tutorials, how-to guides, reference docs, and explanations."

🎯 Documentation Strategy

Quick Analysis

Based on the topic provided, determine which documentation types are needed:

1. **Tutorial** - If users need to learn new skills 2. **How-to** - If users need to solve specific problems 3. **Reference** - If users need to look up technical details 4. **Explanation** - If users need conceptual understanding

Documentation Modes

`--complete` (Complete Documentation Suite)

Create all four documentation types for comprehensive coverage:

/docs-create "authentication system" --complete

Generates:

• `docs/tutorials/authentication-tutorial.md` - Learn to build auth
• `docs/how-to/authentication-tasks.md` - Implement specific auth scenarios
• `docs/reference/authentication-api.md` - Auth API specifications
• `docs/explanation/authentication-concepts.md` - Auth concepts and design

`--learning` (Learning-Oriented)

Focus on tutorial and explanation for education:

/docs-create "machine learning basics" --learning

Generates:

• `docs/tutorials/machine-learning-basics.md` - Hands-on ML introduction
• `docs/explanation/machine-learning-theory.md` - ML theory and concepts

`--working` (Task-Oriented)

Focus on how-to and reference for practical work:

/docs-create "database migrations" --working

Generates:

• `docs/how-to/database-migrations.md` - Migration procedures
• `docs/reference/migration-commands.md` - Migration commands

`--understanding` (Concept-Oriented)

Deep dive into explanation with supporting reference:

/docs-create "distributed systems" --understanding

Generates:

• `docs/explanation/distributed-systems-theory.md` - Distributed systems theory
• `docs/reference/system-specifications.md` - System specifications

Parallel Documentation Specialists

Deploy concurrent documentation agents to create comprehensive documentation: @docs-tutorial-agent @docs-howto-agent @docs-reference-agent @docs-explanation-agent @documentation-agent @architecture-documenter

All agents work in parallel to create complete documentation coverage:

• @docs-tutorial-agent: Create step-by-step learning tutorials with hands-on examples
• @docs-howto-agent: Create practical problem-solving guides for specific tasks
• @docs-reference-agent: Create comprehensive technical reference documentation
• @docs-explanation-agent: Create conceptual understanding and background content
• @documentation-agent: Coordinate structure, cross-references, and quality standards
• @architecture-documenter: Provide system architecture context and design decisions

🔄 Documentation Creation Workflow

Step 1: Analyze Documentation Needs

def analyze_documentation_needs(topic, context):
    """Determine which documentation types are needed."""
    
    needs = {
        'tutorial': False,
        'howto': False,
        'reference': False,
        'explanation': False
    }
    
    # Check for learning needs
    if any(keyword in topic.lower() for keyword in 
           ['learn', 'start', 'begin', 'intro', 'first']):
        needs['tutorial'] = True
    
    # Check for task needs
    if any(keyword in topic.lower() for keyword in
           ['how', 'setup', 'configure', 'deploy', 'fix']):
        needs['howto'] = True
    
    # Check for reference needs
    if any(keyword in topic.lower() for keyword in
           ['api', 'cli', 'config', 'reference', 'spec']):
        needs['reference'] = True
    
    # Check for understanding needs
    if any(keyword in topic.lower() for keyword in
           ['why', 'concept', 'architect', 'design', 'theory']):
        needs['explanation'] = True
    
    return needs

Step 2: Deploy Documentation Agents

Based on analysis and selected mode, deploy appropriate agents to create documentation:

For Learning Mode (--learning)

**Agents Deployed:**

• @docs-tutorial-agent: Creates hands-on learning experience
• @docs-explanation-agent: Provides conceptual understanding
• @documentation-agent: Ensures cross-references and structure

**Files Created:**

• `docs/tutorials/[topic-slug].md` - Step-by-step tutorial
• `docs/explanation/[topic-slug].md` - Conceptual background

For Working Mode (--working)

**Agents Deployed:**

• @docs-howto-agent: Creates practical problem-solving guides
• @docs-reference-agent: Creates technical specifications
• @documentation-agent: Ensures cross-references and structure

**Files Created:**

• `docs/how-to/[topic-slug].md` - Problem-solving procedures
• `docs/reference/[topic-slug].md` - Technical specifications

Step 3: Agent Coordination and Integration

The @documentation-agent coordinates all agents to ensure proper cross-references and integration:

## Documentation Cross-References

### In Tutorial:
- "For specific tasks, see [How-to Guide](../how-to/[topic].md)"
- "For complete details, see [Reference](../reference/[topic].md)"
- "To understand concepts, read [Explanation](../explanation/[topic].md)"

### In How-to:
- "