Document

Overview

Generate or update project documentation with appropriate mermaid diagrams, following existing documentation conventions and ensuring proper formatting.

Arguments

Definitions

•[output-path] (optional): Output file path. If omitted, suggests appropriate location based on content.
•<context> (required): Description of what to document.

Values

$ARGUMENTS

Core Principles

•Use appropriate mermaid diagram types for visual clarity
•Follow existing project documentation style and conventions
•Include practical examples with code snippets
•Link to related documentation when available
•Run markdownlint-cli2 to ensure proper formatting
•Validate mermaid syntax before saving documentation
•Keep diagrams as simple as possible while conveying the necessary information

Skill-Specific Guidelines

Mermaid Diagram Types

Architecture Diagrams

mermaid

graph TB
    subgraph Frontend
        UI[User Interface]
        State[State Management]
    end
    subgraph Backend
        API[API Layer]
        Service[Business Logic]
        DB[(Database)]
    end
    UI --> API
    API --> Service
    Service --> DB

Sequence Diagrams

mermaid

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database

    User->>Frontend: Submit form
    Frontend->>API: POST /data
    API->>Database: INSERT
    Database-->>API: Success
    API-->>Frontend: 200 OK
    Frontend-->>User: Show confirmation

Flowcharts

mermaid

flowchart TD
    A[Start] --> B{Is authenticated?}
    B -->|Yes| C[Show dashboard]
    B -->|No| D[Redirect to login]
    D --> E[User logs in]
    E --> B

Class Diagrams

mermaid

classDiagram
    class User {
        +string id
        +string email
        +login()
        +logout()
    }
    class Session {
        +string token
        +Date expiry
        +refresh()
    }
    User "1" --> "0..*" Session

State Diagrams

mermaid

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: fetch
    Loading --> Success: data received
    Loading --> Error: request failed
    Success --> Idle: reset
    Error --> Loading: retry

Instructions

•
Parse Request
- •Analyze the [context] to understand documentation needs
- •
  Determine documentation type:
  - •API documentation
  - •Architecture documentation
  - •Feature documentation
  - •Setup/installation guides
  - •Troubleshooting guides
  - •Component documentation
•
Analyze Existing Documentation
- •Check for existing docs directory structure
- •Identify related documentation files
- •Understand current documentation conventions
- •Check for documentation templates
•
Explore Codebase
- •Launch explore agents to understand relevant code
- •For API docs: find API routes, handlers, types
- •For architecture: understand component relationships
- •For features: trace feature implementation
•
Generate Documentation
- •Create markdown documentation
- •
  Include mermaid diagrams where appropriate:
  - •Architecture diagrams (C4, component diagrams)
  - •Sequence diagrams (for flows and interactions)
  - •Flowcharts (for decision logic)
  - •Class diagrams (for object models)
  - •State diagrams (for state machines)
- •Follow existing documentation style if present
•
Format Output
- •Run npx markdownlint-cli2 --fix <file> to format
- •Handle formatting errors gracefully
- •Report any issues that couldn't be auto-fixed
•
Save Documentation
- •Save to --output path if specified
- •Otherwise suggest appropriate location based on content type
- •Inform user of saved file path

Output Guidance

Present the saved documentation path and a brief summary:

code

Documentation saved to docs/architecture.md

## Summary
- Type: Architecture documentation
- Diagrams: 3 (component, sequence, flowchart)
- Sections: 5
- Examples: 2 code snippets

The documentation has been formatted with markdownlint-cli2.

On error:

code

Failed to generate documentation: <error description>

Templates

Documentation Structure

markdown

# {{title}}

<!--
Instructions:
- Replace {{title}} with a descriptive document title
- Use title case (e.g., "API Reference", "Authentication Flow")
-->

## Overview

{{overview}}

<!--
Instructions:
- Replace {{overview}} with a brief description of what this document covers
- Keep it to 2-4 sentences
-->

## {{main_section}}

{{main_content}}

<!--
Instructions:
- Replace {{main_section}} with appropriate section name
- Replace {{main_content}} with detailed content
- Include code examples and diagrams as needed
- Add multiple sections as required
-->

### Diagrams

```mermaid
{{diagram}}
```

<!--
Instructions:
- Replace {{diagram}} with appropriate mermaid diagram
- Choose diagram type based on content (flowchart, sequence, class, etc.)
- Keep diagrams simple and focused
-->

## Examples

{{examples}}

<!--
Instructions:
- Replace {{examples}} with practical usage examples
- Include code snippets where helpful
-->

## Related

{{related_links}}

<!--
Instructions:
- Replace {{related_links}} with links to related documentation
- Use markdown link format: [Link Text](url)
-->