/docs-add

allowed-tools: Read, Write, Edit, Bash(fd:*), Bash(rg:*), Bash(jq:*), Bash(gdate:*), WebFetch, Task
name: "Docs Add"
description: "Generate comprehensive documentation with intelligent content organization and Docusaurus integration"
author: "wcygan"
tags: ["docs","manage"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

Context

• Session ID: !`gdate +%s%N`
• Current directory: !`pwd`
• Target: $ARGUMENTS
• Project structure: !`fd . -t d -d 2 | head -10 || echo "No subdirectories found"`
• Docusaurus indicators: !`fd "docusaurus.config.js" . -d 3 | head -3 || echo "No Docusaurus config found"`
• Existing docs: !`fd "docs" . -t d -d 2 | head -5 || echo "No docs directories found"`
• Documentation files: !`fd "\.(md|mdx)$" docs/ 2>/dev/null | wc -l | tr -d ' ' || echo "0"`
• Sidebar config: !`fd "sidebars.js" . -d 3 | head -1 || echo "No sidebar config found"`
• Technology stack: !`fd "(package\.json|deno\.json|Cargo\.toml|go\.mod)" . -d 2 | head -3 || echo "Unknown stack"`
• Git status: !`git status --porcelain docs/ 2>/dev/null | wc -l | tr -d ' ' || echo "0"` docs changes

Your task

STEP 1: Initialize documentation generation session

• CREATE session state file: `/tmp/docs-add-state-$SESSION_ID.json`
• SET initial state:

  {
    "sessionId": "$SESSION_ID",
    "timestamp": "ISO_8601_TIMESTAMP",
    "phase": "initialization",
    "target_content": "$ARGUMENTS",
    "project_analysis": {
      "has_docusaurus": false,
      "docs_directory": null,
      "existing_structure": {},
      "technology_stack": [],
      "content_type": "unknown"
    },
    "generation_plan": {
      "content_type": null,
      "placement_strategy": null,
      "template_selection": null,
      "sidebar_updates": false
    },
    "checkpoints": {},
    "artifacts": {
      "generated_files": [],
      "updated_configs": [],
      "validation_results": {}
    }
  }

• CREATE documentation workspace: `/tmp/docs-add-workspace-$SESSION_ID/`

STEP 2: Analyze existing documentation structure and requirements

Think deeply about optimal documentation organization strategy based on detected project characteristics and existing structure.

TRY:

• ANALYZE project structure from Context section
• DETECT documentation framework and existing organization
• DETERMINE content type from $ARGUMENTS:

IF $ARGUMENTS contains "guide":

• SET content_type = "guide"
• SET template = "step-by-step-guide"

ELSE IF $ARGUMENTS contains "api":

• SET content_type = "api"
• SET template = "api-reference"

ELSE IF $ARGUMENTS contains "tutorial":

• SET content_type = "tutorial"
• SET template = "progressive-tutorial"

ELSE IF $ARGUMENTS contains "diagram":

• SET content_type = "diagram"
• SET template = "mermaid-diagram"

ELSE IF $ARGUMENTS contains "troubleshooting":

• SET content_type = "troubleshooting"
• SET template = "problem-solution"

ELSE:

• SET content_type = "general"
• SET template = "basic-documentation"

• UPDATE session state with analysis results

CATCH (analysis_failed):

• LOG error details to session state
• SET content_type = "general" as fallback
• CONTINUE with basic documentation generation

STEP 3: Determine optimal placement and generation strategy

Think harder about content organization, cross-referencing, and integration with existing documentation architecture.

IF no docs/ directory exists:

• RECOMMEND running `/docs-init` first
• EXIT with setup instructions

ELSE:

• ANALYZE existing sidebar structure
• DETERMINE appropriate category placement
• IDENTIFY cross-reference opportunities
• PLAN sidebar integration strategy

IF content is complex (multiple sections OR >1000 words expected):

• Consider using Task tool for parallel content generation:
• **Content Structure Agent**: Outline and organization
• **Examples Generator Agent**: Code examples and samples
• **Cross-Reference Agent**: Links and related content
• **Template Customization Agent**: Project-specific adaptations

STEP 4: Generate documentation content using intelligent templates

TRY:

CASE content_type: WHEN "guide":

• GENERATE step-by-step guide structure:

  # {TITLE}

  ## Overview

  Brief description and scope

  ## Prerequisites

  - Required knowledge
  - Dependencies needed

  ## Step-by-Step Instructions

  ### Step 1: {Action}

  Detailed instructions with examples

  ## Troubleshooting

  Common issues and solutions

  ## Next Steps

  Related documentation

WHEN "api":

• GENERATE API reference structure:

  # {TITLE} API Reference

  ## Overview

  API purpose and base URL

  ## Authentication

  Security requirements

  ## Endpoints

  ### GET /endpoint

  - **Description**: Functionality
  - **Parameters**: Input requirements
  - **Response**: Output format
  - **Examples**: Sample requests/responses

  ## Error Handling

  Status codes and error responses

WHEN "tutorial":

• GENERATE progressive tutorial structure:

  # {TITLE} Tutorial

  ## What You'll Learn

  Learning objectives

  ## What You'll Build

  End result description

  ## Tutorial Steps

  ### Part 1: Foundation

  Basic concepts and setup

  ### Part 2: Implementation

  Core functionality

  ### Part 3: Enhancement

  Advanced features

  ## Summary and Next Steps

  Recap and further reading

WHEN "diagram":

• GENERATE Mermaid diagram structure:

  # {TITLE}

  ## Overview

  Context and purpose

  ```mermaid
  graph TD
      A[Component A] --> B[Component B]
      B --> C[Component C]

  ## Components
  Description of diagram elements

  ## Related Documentation
  Links to detailed docs

WHEN "troubleshooting":

- GENERATE problem-solution structure:
  ```markdown
  # {TITLE} Troubleshooting

  ## Common Issues

  ### Issue: {Problem Description}

  **Symptoms**: What users experience
  **Cause**: Root cause explanation\
  **Solution**: Step-by-step