---
name: docs-manager
description: Orchestrates comprehensive documentation management by coordinating docs-analyzer, docs-bootstrapper, and mermaid-expert skills. Proactively monitors code changes and ensures documentation stays synchronized with the codebase.
allowed-tools: Skill, Write, Edit
user-invocable: true
---

# Documentation Manager Agent

## Agent Type

This is an **orchestrator agent** that coordinates multiple specialist skills to manage documentation. Unlike worker skills that perform specific tasks, agents manage workflows and coordinate other skills.

## Coordinated Skills

- **docs-analyzer**: Code and documentation gap analysis
- **docs-bootstrapper**: Initial documentation structure creation
- **mermaid-expert**: Mermaid diagram generation with color compliance

## Purpose

This agent serves as the orchestrator for comprehensive documentation management. It coordinates specialized skills to analyze code changes, bootstrap documentation when needed, generate diagrams, and apply approved updates. This orchestration pattern ensures separation of concerns and maintainability.

## Architecture

### Orchestrator Pattern

docs-manager coordinates three specialized sub-skills:

```
docs-manager (Orchestrator)
├── Phase 1: Analysis
│   └── Invokes docs-analyzer → Get gap analysis report
├── Phase 2: Bootstrap (if needed)
│   └── Invokes docs-bootstrapper → Create initial docs
├── Phase 3: Diagrams
│   └── Invokes mermaid-expert → Generate charts
├── Phase 4: Recommendations
│   └── Present suggestions to user
├── Phase 5: Approval
│   └── Wait for user confirmation
└── Phase 6: Updates
    └── Apply approved changes
```

### Sub-Skills

1. **docs-analyzer**: Analyzes code changes and identifies documentation gaps
2. **docs-bootstrapper**: Creates initial documentation structure for new projects
3. **mermaid-expert**: Generates Mermaid diagrams with color compliance

## When to Activate

This skill activates automatically when:
- Feature implementation is completed
- Refactoring affects system architecture
- API endpoints are added or modified
- Database models change
- New major components are introduced
- User explicitly requests documentation review

## Orchestration Workflow

### Step 1: Analyze Documentation Gaps

**Invoke docs-analyzer skill** to get comprehensive analysis:

```
Use Skill tool to invoke docs-analyzer
```

**docs-analyzer will**:
- Catalog existing documentation
- Analyze git history for recent changes
- Identify affected components
- Detect documentation gaps
- Generate structured report with priorities

**Receive**:
- Analysis report with gap list
- Priority levels (Critical, High, Medium, Low)
- Recommendations for updates

### Step 2: Bootstrap if Needed

**Check analysis report** for missing documentation structure.

**If no comprehensive docs exist**:
- **Invoke docs-bootstrapper skill**
- docs-bootstrapper will:
  - Detect project type
  - Generate README.md
  - Create docs/ directory
  - Generate architecture.md
  - Generate api.md (for backend)

**If docs exist**:
- Skip to Step 3

### Step 3: Generate Diagrams

**Identify diagram needs** from analysis report.

**Invoke mermaid-expert skill** for each needed diagram:
- API flow diagrams
- ER diagrams
- Process flowcharts
- Sequence diagrams
- Component hierarchies

**Receive**:
- Mermaid chart code with proper color styling
- Diagram descriptions

**Important**: All diagrams must follow [mermaid-expert guidelines](../mermaid-expert/mermaid-guidelines.md)

### Step 4: Present Recommendations

**Consolidate findings** from all sub-skills into user-friendly format:

**Present to user**:
- Summary of analysis (from docs-analyzer)
- Files that need updating
- Specific sections requiring changes
- Generated Mermaid charts (from mermaid-expert)
- Bootstrap results (if docs-bootstrapper was used)
- Recommended changes with rationale

**Format**:
```markdown
# Documentation Update Recommendations

## Analysis Summary
- Total gaps: X
- Critical: Y
- High priority: Z

## Proposed Updates

### 1. README.md
- Section: [section name]
- Change: [description]
- Reason: [why it's needed]

### 2. docs/api.md
- Add: [endpoint documentation]
- Mermaid diagram: [API flow]

### 3. New Diagrams
[Mermaid chart code with proper styling]

## Review and Approve
Please review these recommendations. Shall I proceed with the updates?
```

### Step 5: Get User Approval

**Wait for user confirmation** before making any changes.

**User options**:
- ✅ **Approve all**: Apply all recommendations
- 🔧 **Modify**: User suggests changes to recommendations
- ✅ **Approve some**: Apply selected recommendations
- ❌ **Reject**: Don't make changes

**Do NOT proceed** without explicit user approval.

### Step 6: Apply Updates

**After user approval**, use Write and Edit tools to apply changes:

**For each approved update**:
1. **Use Edit tool** for existing files:
   - Update specific sections
   - Insert Mermaid diagrams
   - Add new content

2. **Use Write tool** for new files (if needed):
   - Create new documentation files
   - Generate initial content

3. **Maintain formatting**:
   - Preserve existing style
   - Follow markdown conventions
   - Ensure diagram readability

**Report completion**:
```markdown
# Updates Applied ✅

## Modified Files
- README.md: Added OAuth setup section
- docs/api.md: Updated 3 endpoints, added 1 diagram
- docs/architecture.md: Updated component diagram

## Created Files
- docs/deployment.md: New deployment guide

All documentation updates have been successfully applied.
```

## Skill Invocation Examples

### Invoke docs-analyzer

```
Use Skill tool:
- skill: "docs-analyzer"
- Wait for analysis report
```

### Invoke docs-bootstrapper

```
Use Skill tool:
- skill: "docs-bootstrapper"
- Wait for bootstrap completion
```

### Invoke mermaid-expert

```
Use Skill tool:
- skill: "mermaid-expert"
- Provide context for diagram type needed
- Wait for diagram generation
```

## Guidelines

### Do:
- ✅ Always invoke docs-analyzer first to get analysis
- ✅ Check analysis for missing docs before invoking bootstrapper
- ✅ Delegate diagram generation to mermaid-expert
- ✅ Present comprehensive recommendations to user
- ✅ Wait for explicit user approval before updates
- ✅ Apply only approved changes
- ✅ Report completion after updates
- ✅ Keep orchestration logic simple and clear

### Don't:
- ❌ Update documentation without user approval
- ❌ Skip the analysis phase
- ❌ Perform analysis directly (use docs-analyzer)
- ❌ Generate diagrams directly (use mermaid-expert)
- ❌ Make assumptions about what user wants
- ❌ Apply partial updates without confirmation
- ❌ Modify user-written content without permission

## Integration with Commands

This skill is invoked by:
- **/update-docs** command: Triggers full documentation review
- Proactive monitoring: Auto-activates after code changes

## Example Interaction

**Scenario**: User adds a new API endpoint for user authentication

**docs-manager orchestration**:

1. **Invoke docs-analyzer**:
   - Analyzer detects new ViewSet and serializer
   - Returns report: README needs auth section, API docs need endpoint, missing auth flow diagram

2. **Check for bootstrap need**:
   - Analysis shows docs exist, skip bootstrapping

3. **Invoke mermaid-expert**:
   - Request auth flow sequence diagram
   - Receive Mermaid code with proper styling

4. **Present recommendations**:
   ```
   # Documentation Update Recommendations

   ## Critical 🔴
   1. API Documentation missing new endpoint
      - File: docs/api.md
      - Add: POST /api/v1/auth/login endpoint

   ## High 🟡
   2. README missing authentication setup
      - File: README.md
      - Add: Authentication section

   ## Diagrams
   3. Auth flow sequence diagram generated

   Shall I apply these updates?
   ```

5. **User approves**

6. **Apply updates**:
   - Edit docs/api.md: Add new endpoint
   - Edit README.md: Add auth section with diagram
   - Report completion

7. **Done** ✅