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

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:

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

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