update-docs

What this skill does

# 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:

```text
$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**

```bash
# 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, breaking changes
       - IMPORTANT: New features, configuration options
       - NICE_TO_HAVE: Code comments, minor clarifications
   - Collect all documentation requirement reports

8. **Launch `sdd:tech-writer` agents for documentation (parallel)** (Sonnet or Opus models)
   - Launch one tech-writer agent per documentation area
   - Provide each agent with:
     - **Context**: Documentation requirements from analysis agent
     - **Target**: Specific documentation files to create/update
     - **Documentation tasks**: List from analysis agent
     - **Guidance**: Read Tech Writer Agent @/plugins/sdd/agents/tech-writer.md for best practices
     - **Resources**: Existing documentation for style reference
     - **Goal**: Create/update comprehensive documentation
     - **Constraints**:
       - Follow existing documentation patterns
       - Include working code examples
       - Avoid documentation bloat
       - Focus on user tasks, not implementation details

9. **Launch quality review agents (parallel)** (Sonnet or Opus models)
   - Launch `sdd:tech-writer` agents again for quality review
   - Provide:
     - **Context**: Original changes + new documentation created
     - **Goal**: Verify documentation quality and completeness
     - **Review criteria**:
       - All user-facing changes are documented
       - Code examples are accurate and work
       - Links and references are valid
       - Documentation follows project conventions
       - No unnecessary documentation bloat
     - **Output**: PASS confirmation or list of issues to fix

10. **Iterate if needed**
    - If any documentation areas have quality issues: Return to step 8
    - Launch new tech-writer agents only for areas with gaps
    - Provide specific instructions on what needs fixing
    - Continue until all documentation passes quality review

11. **Final verification**
    - Review all documentation changes holistically
    - Verify cross-references between documents work
    - Ensure no conflicting information
    - Confirm documentation structure is navigable

## Success Criteria

- All user-facing changes have appropriate documentation ✅
- Code examples are accurate and tested ✅
- Documentation fo