/docs-update

allowed-tools: Read, Write, Edit, MultiEdit, Bash(fd:*), Bash(rg:*), Bash(git:*), Bash(jq:*), Bash(gdate:*), Bash(node:*), Bash(npm:*), Task
name: "Docs Update"
description: "Update and maintain Docusaurus documentation by analyzing codebase changes with automated content refresh"
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 2>/dev/null || date +%s000000000 2>/dev/null || echo "1751901071157927000"`
• Current directory: !`pwd`
• Target: $ARGUMENTS
• Documentation directory: !`fd -t d "docs" . -d 2 | head -1 || echo "No docs directory found"`
• Docusaurus config: !`fd "docusaurus.config.js" . -d 3 | head -1 || echo "No docusaurus config found"`
• Git status: !`git status --porcelain | wc -l | tr -d ' ' || echo "0"` files changed
• Project structure: !`fd . -t d -d 2 | head -8 || echo "No subdirectories found"`
• API specs: !`fd "(openapi|swagger)\.(yaml|yml|json)$" . -d 3 | head -3 || echo "No API specs found"`
• JSDoc files: !`rg -l "@param|@returns|@example" --type typescript --type javascript . | wc -l | tr -d ' ' || echo "0"` files with JSDoc
• Node.js available: !`which node 2>/dev/null && echo "available" || echo "not available"`

Your Task

STEP 1: Initialize documentation update session with state management

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

  {
    "sessionId": "$SESSION_ID",
    "timestamp": "ISO_8601_TIMESTAMP",
    "phase": "initialization",
    "target_scope": "$ARGUMENTS",
    "project_analysis": {
      "has_docs_directory": false,
      "has_docusaurus_config": false,
      "api_specs_count": 0,
      "jsdoc_files_count": 0,
      "git_changes_count": 0
    },
    "update_sources": [],
    "documentation_state": {},
    "validation_results": {},
    "performance_metrics": {
      "start_time": "ISO_8601_TIMESTAMP",
      "phase_timings": {},
      "total_duration": null
    },
    "error_recovery": {
      "failed_operations": [],
      "recovery_attempts": [],
      "partial_completions": []
    }
  }

• CREATE documentation workspace: `/tmp/docs-update-$SESSION_ID/`
• VALIDATE prerequisite tools and environment

STEP 2: Project analysis and documentation scope determination

Think deeply about the optimal documentation update strategy based on the detected project characteristics and existing documentation state.

IF no documentation directory found:

• LOG missing docs directory to session state
• RECOMMEND running `/docs-init` first
• PROVIDE guidance on documentation setup
• EXIT with helpful instructions

ELSE:

• ANALYZE project structure from Context section
• DETERMINE update scope based on $ARGUMENTS:
• IF no arguments: UPDATE all sources (codebase, api, git, sidebar)
• IF "codebase": FOCUS on code documentation extraction
• IF "api": FOCUS on API specification updates
• IF "validate": FOCUS on content validation and fixing
• IF "sidebar": FOCUS on navigation regeneration
• ELSE: PARSE custom scope from arguments

• UPDATE session state with analysis results

STEP 3: Documentation source analysis and update strategy

CASE update_scope: WHEN "all" OR "codebase":

TRY:

**Codebase Analysis and Documentation Extraction:**

• SCAN for Mermaid diagrams in existing documentation:
• DETECT existing diagrams with fd and rg
• VALIDATE diagram syntax and formatting
• UPDATE content based on code architecture changes
• INTEGRATE with Docusaurus Mermaid theme configuration

• EXTRACT code documentation:

• SCAN TypeScript/JavaScript files for JSDoc comments
• EXTRACT function signatures and type definitions
• GENERATE API reference documentation from exports
• UPDATE configuration documentation from config files
• PROCESS language-specific documentation patterns

CATCH (codebase_analysis_failed):

• LOG analysis errors to session state
• ATTEMPT alternative extraction methods
• CONTINUE with partial results
• SAVE error details for manual review

WHEN "all" OR "api":

TRY: **API Documentation Integration:**

• PARSE API specification files (openapi.yaml, swagger.json)
• GENERATE endpoint documentation with examples
• CREATE request/response schemas
• UPDATE authentication documentation
• SUPPORT multiple formats:
• OpenAPI 3.x specifications
• Swagger 2.0 specifications
• Postman collections (via conversion)
• GraphQL schemas (via introspection)

CATCH (api_documentation_failed):

• LOG API processing errors to session state
• ATTEMPT alternative parsing methods
• CONTINUE with available API documentation
• PROVIDE manual API documentation instructions

WHEN "all" OR includes git analysis:

TRY: **Git History Analysis and Changelog Generation:**

• ANALYZE commit messages using conventional commit format
• GROUP changes by type (feat, fix, docs, refactor, etc.)
• EXTRACT breaking changes and migration notes
• UPDATE version history and release notes
• DETECT API breaking changes from code diffs
• GENERATE migration guides for major version updates
• DOCUMENT deprecated features and replacement APIs
• CREATE upgrade instructions with examples

CATCH (git_analysis_failed):

• LOG git operation errors to session state
• ATTEMPT alternative history analysis methods
• CONTINUE with available git information
• PROVIDE manual changelog instructions

STEP 4: Advanced documentation processing for complex projects

IF project has >100 documentation files OR multiple API specs:

Think harder about enterprise documentation coordination strategies and optimal sub-agent delegation patterns.

• USE Task tool for parallel documentation processing:

1. **Codebase Documentation Agent**: Extract and process all code documentation

• SAVE findings to: `/tmp/docs-update-$SESSION_ID/codebase-docs.json`

2. **API Documentation Agent**: Process all API specifications and generate endpoint docs

• SAVE findings to: `/tmp/docs-update-$SESSION_ID/api-docs