/update-docs

name: update-docs
description: Update and maintain project documentation for local code changes using multi-agent workflow with tech-writer agents. Covers docs/, READMEs, JSDoc, and API documentation.

Update Documentation for Local Changes

<task> You are a technical documentation specialist who maintains living documentation that serves real user needs. Your mission is to create clear, concise, and useful documentation while ruthlessly avoiding documentation bloat and maintenance overhead. </task>

<context> References:

• Tech Writer Agent: @/plugins/sdd/agents/tech-writer.md
• Documentation principles and quality standards
• Token efficiency and progressive disclosure patterns
• Context7 MCP for accurate technical information gathering

</context>

User Arguments

User can provide specific focus areas or documentation types:

$ARGUMENTS

If nothing is provided, focus on all documentation needs for uncommitted changes. If everything is committed, cover the latest commit.

Context

After implementing new features or refactoring existing code, documentation must be updated to reflect changes. This command orchestrates automated documentation updates using specialized tech-writer agents and parallel analysis.

Goal

Ensure all code changes are properly documented with clear, maintainable documentation that helps users accomplish real tasks.

Important Constraints

• **Focus on user-facing impact** - not every code change needs documentation
• **Preserve existing documentation style** - follow established patterns
• **Analyse complexity of changes**:
• If there are 3+ changed files affecting documentation, or significant API changes → **Use multi-agent workflow**
• If there are 1-2 simple changes → **Write documentation yourself**
• **Documentation must justify its existence** - avoid bloat and maintenance overhead

Workflow Steps

Preparation

1. **Read SADD skill if available**

• If available, read the SADD skill to understand best practices for managing agents

2. **Discover documentation infrastructure**

• CRITICAL: You MUST read root README.md and project config (package.json, pyproject.toml, etc.)
• Identify existing documentation structure (docs/, README files, JSDoc)
• Understand project conventions and documentation patterns
• Check for documentation generation tools (OpenAPI, JSDoc, TypeDoc)

3. **Inventory existing documentation**

# Find all documentation files
find . -name "*.md" -o -name "*.rst" | grep -E "(README|CHANGELOG|CONTRIBUTING|docs/)"

# Check for generated docs
find . -name "openapi.*" -o -name "*.graphql" -o -name "swagger.*"

Analysis

Do steps 4-5 in parallel using haiku agents:

4. **Analyze documentation structure**

• Launch haiku agent to map existing documentation:
• Identify docs/ folder structure and organization
• Find all README.md files and their purposes
• Locate API documentation (generated or manual)
• Note JSDoc/TSDoc patterns in codebase
• Output: Documentation map with locations and types

5. **Analyze local changes**

• Run `git status -u` to identify all changed files (including untracked)
• If no uncommitted changes, run `git show --name-status` for latest commit
• Filter to identify documentation-impacting changes:
• New/modified public APIs
• Changed module structures
• Updated configuration options
• New features or workflows
• Launch separate haiku agents per changed file to:
• Analyze the file and its documentation impact
• Identify what documentation needs to be created/updated
• Identify index documents that need updates (see Index Documents section)
• Prepare short summary of documentation requirements
• Extract list of documentation tasks

Documentation Planning

6. **Group changes by documentation area**

• Aggregate analysis results from haiku agents
• Group changes that can be covered by same documentation update:
• **API Documentation**: All API changes → single agent
• **Module READMEs**: Changes in same module → single agent
• **User Guides**: Related feature changes → single agent
• **JSDoc/Code Comments**: Complex logic changes → per-file agents
• **Index Documents**: Updates to navigation and discovery docs → single agent
• Identify index documents requiring updates:
• Root `README.md` - if new modules/features affect project overview, High probability of needing update.
• Module `README.md` - if module's purpose, exports, or usage changed
• `docs/` index files - if documentation structure changed
• Create documentation task assignments

Documentation Writing

Simple Change Flow (1-2 files, minor updates)

If changes are simple, write documentation yourself following this guideline:

1. Read Tech Writer Agent guidelines from @/plugins/sdd/agents/tech-writer.md 2. Review the changed files and understand the impact 3. Identify which documentation needs updates 4. Make targeted updates following project conventions 5. Verify all links and examples work 6. Ensure documentation serves real user needs

Ensure documentation:

• Follows project style and conventions
• Includes working code examples
• Avoids duplication with existing docs
• Helps users accomplish tasks

Multi-Agent Flow (3+ files or significant changes)

If there are multiple changed files or significant documentation needs, use specialized agents:

7. **Launch `doc-analysis` agents (parallel)** (Haiku models)

• Launch one analysis agent per documentation area identified
• Provide each agent with:
• **Context**: What changed in related files (git diff)
• **Target**: Which documentation area to analyze
• **Resources**: Existing documentation in that area
• **Goal**: Create detailed documentation requirements
• **Output**: Specific documentation tasks with priorities:
• CRITICAL: User-facing API changes, break