Documentation Production

Documentation Production

Overview

Provide a consistent, low-friction workflow for producing documentation across formats: focused docs, indexes, diagrams, tutorials, and learning paths. Keep outputs structured and aligned with the repo's docs conventions.

When to Use

• Generating or updating documentation for components, APIs, or features
• Building a project index or knowledge base
• Creating Mermaid diagrams for system behavior or architecture
• Writing tutorials, workshops, or learning paths
• Explaining concepts for onboarding or education

Avoid when:

• The request is primarily a code change (use implementation workflows)
• The doc type is a one-off note that doesn't need structure

Quick Reference

Workflow

1. Identify doc type and target audience. 2. Load the relevant reference file(s) for structure and patterns. 3. Gather source material from code or existing docs. 4. Produce the artifact using the required format. 5. Validate accuracy and consistency with repo conventions. 6. Summarize changes and next steps.

Output

• The documentation artifact(s)
• Brief change summary and any follow-up gaps

Common Mistakes

• Skipping source review and guessing behavior
• Mixing tutorial/guide formats without clear intent
• Creating diagrams without labels or accessibility notes
• Updating docs without adjusting indexes or nav links

Reference: diagrams

/docs:diagrams - Mermaid Diagram Builder

Triggers

• Requests for system, workflow, or API visualizations
• Documentation needing flowcharts, sequence diagrams, ERDs, or timelines
• Architecture or process explanations that benefit from diagrams
• User journeys, state machines, or decision tree visualizations

Usage

/docs:diagrams [description|input] [--type flowchart|sequence|erd|state|gantt|timeline|class|journey|quadrant|pie|gitgraph] [--style basic|styled]

Behavioral Flow

1. Scope: Identify entities, relationships, and target audience 2. Select: Choose the best Mermaid diagram type for the data 3. Draft: Produce a clean base diagram and a styled variant 4. Validate: Ensure readability, labeling, and rendering compatibility 5. Deliver: Provide render tips, export formats, and alternatives

Key behaviors:

• Always deliver both basic and styled Mermaid code blocks
• Include comments for non-obvious Mermaid syntax
• Provide at least one alternative diagram option when multiple types fit
• Add accessibility notes (color contrast, labels, reading order)

Delegation Protocol

When to delegate (use Task tool):

• ✅ Complex diagrams with >10 nodes or >2 lanes
• ✅ Multi-diagram deliverables (e.g., sequence + ERD)
• ✅ Architecture visualizations needing layering and annotations

Available subagents:

• mermaid-expert: Diagram selection, Mermaid syntax, styling, and export guidance

Delegation strategy:

<function_calls>
<invoke name="Task">
  <subagent_type>mermaid-expert</subagent_type>
  <description>Create Mermaid diagrams from the provided description</description>
  <prompt>
    Build Mermaid diagrams with both basic and styled variants.
    Requirements:
    - Choose the best diagram type
    - Provide alternative option if applicable
    - Include comments for complex syntax
    - Add rendering and export recommendations
  </prompt>
</invoke>
</function_calls>

When NOT to delegate (use direct tools):

• ❌ Single, simple diagram (<6 nodes)
• ❌ Minor tweaks to existing Mermaid code

Tool Coordination

• Task tool: Delegates to mermaid-expert for complex diagram requests
• Read: Ingest specs or existing docs
• Write: Deliver Mermaid code in documentation files

Examples

Flowchart

/docs:diagrams "User login flow with MFA and lockout" --type flowchart

Sequence Diagram

/docs:diagrams "Checkout API interaction across frontend, payments, and inventory" --type sequence

ERD

/docs:diagrams "Customer, Order, Invoice, Payment schema" --type erd

Boundaries

Will:

• Produce clear Mermaid diagrams with basic + styled variants
• Add labels, comments, and accessibility guidance
• Suggest export formats and tooling for rendering

Will Not:

• Ship diagrams without confirming intent or scope when inputs are ambiguous
• Produce unreadable, overly dense diagrams without proposing simplifications

Reference: generate

/docs:generate - Focused Documentation Generation

Triggers

• Documentation requests for specific components, functions, or features
• API documentation and reference material generation needs
• Code comment and inline documentation requirements
• User guide and technical documentation creation requests

Usage

/docs:generate [target] [--type inline|external|api|guide] [--style brief|detailed]

Behavioral Flow

1. Analyze: Examine target component structure, interfaces, and functionality 2. Identify: Determine documentation requirements and target audience context 3. Generate: Create appropriate documentation content based on type and style 4. Format: Apply consistent structure and organizational patterns 5. Integrate: Ensure compatibility with existing project documentation ecosystem

Key behaviors:

• Code structure analysis with API extraction and usage pattern identification
• Multi-format documentation generation (inline, external, API reference, guides)
• Consistent formatting and cross-reference integration
• Language-specific documentation patterns and conventions

Personas (Thinking Modes)

• technical-writer: Clear communication, audience-appropriate language, comprehensive coverage
• developer: Code understanding, practical examples, implementation focus

Delegation Protocol

When to delegate (use Task tool):

• ✅ API documentation (>5 endpoints or complex interfaces)
• ✅ Multi-component documentation projects
• ✅ Comprehensive user guides requiring >10 pages
• ✅ Documentation requiring deep code analysis

Available subagents:

• technical-writer: User guides, tutorials, explanatory documentation
• api-documenter: API reference, endpoint documentation, schemas

Delegation strategy for API docs:

<invoke name="Task">
  <subagent_type>api-documenter</subagent_type>
  <description>Generate API documentation for [path]</description>
  <prompt>
    Create comprehensive API documentation:
    - Endpoint descriptions
    - Request/response schemas
    - Authentication requirements
    - Usage examples
    - Error responses
    Style: [brief|detailed]
  </prompt>
</invoke>

Delegation strategy for user guides:

<invoke name="Task">
  <subagent_type>technical-writer</subagent_type>
  <description>Generate user guide for [feature]</description>
  <prompt>
    Create user-focused documentation:
    - Feature overview
    - Step-by-step tutorials
    - Code examples
    - Common use cases
    - Troubleshooting
  </prompt>
</invoke>

When NOT to delegate (use direct tools):

• ❌ Simple inline comments (single file, <50 lines)
• ❌ Basic JSDoc/docstring generation
• ❌ Quick README updates

Tool Coordination

• Task tool: Delegates to technical-writer or api-documenter for complex docs
• Read: Component analysis (direct or by subagent)
• Grep: Reference extraction (direct or by subagent)
• Write: Documentation file creation (direct for simple, by subagent for complex)
• Glob: Multi-file coordination

Key Patterns

• Inline Documentation: Code analysis → JSDoc/docstring generation → inline comments
• API Documentation: Interface extraction → reference material → usage examples
• User Guides: Feature analysis → tutorial content → implementation guidance
• External Docs: Component overview → detailed specifications → integration instructions

Examples

Inline Code Documentation

/docs:generate src/auth/login.js --type inline
# Generates JSDoc comments with parameter and return descriptions
# Adds comprehensive inline documentation for functions and classes

API Reference Generation

/docs:generate src/api --type api --style detailed
# Creates comprehensive API documentation with endpoints and schemas
# Generates usage examples and integration guidelines

User Guide Creation

/docs:generate payment-module --type guide --style brief
# Creates user-focused documentation with practical examples
# Focuses on implementation patterns and common use cases

Component Documentation

/docs:generate components/ --type external
# Generates external documentation files for component library
# Includes props, usage examples, and integration patterns

Boundaries

Will:

• Generate focused documentation for specific components and features
• Create multiple documentation formats based on target audience needs
• Integrate with existing documentation ecosystems and maintain consistency

Will Not:

• Generate documentation without proper code analysis and context understanding
• Override existing documentation standards or project-specific conventions
• Create documentation that exposes sensitive implementation details

Reference: index

/docs:index - Project Documentation

Triggers

• Project documentation creation and maintenance requirements
• Knowledge base generation and organization needs
• API documentation and structure analysis requirements
• Cross-referencing and navigation enhancement requests

Usage

/docs:index [target] [--type docs|api|structure|readme] [--format md|json|yaml]

Behavioral Flow

1. Analyze: Examine project structure and identify key documentation components 2. Organize: Apply intelligent organization patterns and cross-referencing strategies 3. Generate: Create comprehensive documentation with framework-specific patterns 4. Validate: Ensure documentation completeness and quality standards 5. Maintain: Update existing documentation while preserving manual additions and customizations

Key behaviors:

• Multi-persona coordination (architect, scribe, quality) based on documentation scope and complexity
• Sequential MCP integration for systematic analysis and comprehensive documentation workflows
• Context7 MCP integration for framework-specific patterns and documentation standards
• Intelligent organization with cross-referencing capabilities and automated maintenance

MCP Integration

• Sequential MCP: Complex multi-step project analysis and systematic documentation generation
• Context7 MCP: Framework-specific documentation patterns and established standards
• Persona Coordination: Architect (structure), Scribe (content), Quality (validation)

Personas (Thinking Modes)

• architect: Structural organization, cross-referencing strategy, logical documentation hierarchy
• technical-writer: Clear communication, audience-appropriate content, comprehensive coverage
• quality-engineer: Documentation completeness, accuracy verification, standards compliance

Delegation Protocol

When to delegate (use Task tool):

• ✅ Large project documentation (>10 components)
• ✅ Comprehensive API documentation
• ✅ Knowledge base generation
• ✅ Multi-type documentation (structure + API + guides)

Available subagents:

• Explore: Project structure analysis, component discovery, relationship mapping
• technical-writer: User guides, tutorials, knowledge base content
• api-documenter: API reference documentation, endpoint descriptions, schemas

Delegation strategy for comprehensive docs:

<function_calls>
<invoke name="Task">
  <subagent_type>Explore</subagent_type>
  <description>Analyze project structure and components</description>
  <prompt>
    Explore project for documentation:
    - Component identification
    - API endpoints discovery
    - Architecture patterns
    - Cross-reference opportunities
  </prompt>
</invoke>
<invoke name="Task">
  <subagent_type>api-documenter</subagent_type>
  <description>Generate API documentation</description>
  <prompt>
    Create API documentation:
    - Endpoint descriptions
    - Request/response schemas
    - Authentication
    - Usage examples
    Format: [md|json|yaml]
  </prompt>
</invoke>
<invoke name="Task">
  <subagent_type>technical-writer</subagent_type>
  <description>Generate project documentation</description>
  <prompt>
    Create project docs with architect guidance:
    - Project structure overview
    - Component relationships
    - Getting started guide
    - Cross-references
  </prompt>
</invoke>
</function_calls>

When NOT to delegate (use direct tools):

• ❌ Simple README updates
• ❌ Single component documentation
• ❌ Quick API reference for <5 endpoints

Tool Coordination

• Task tool: Delegates to Explore, technical-writer, api-documenter for comprehensive documentation
• Read/Grep/Glob: Project analysis (by subagents for complex, direct for simple)
• Write: Documentation creation (by subagents for complex, direct for simple)
• TodoWrite: Progress tracking for multi-component workflows

Key Patterns

• Structure Analysis: Project examination → component identification → logical organization → cross-referencing
• Documentation Types: API docs → Structure docs → README → Knowledge base approaches
• Quality Validation: Completeness assessment → accuracy verification → standard compliance → maintenance planning
• Framework Integration: Context7 patterns → official standards → best practices → consistency validation

Examples

Project Structure Documentation

/docs:index project-root --type structure --format md
# Comprehensive project structure documentation with intelligent organization
# Creates navigable structure with cross-references and component relationships

API Documentation Generation

/docs:index src/api --type api --format json
# API documentation with systematic analysis and validation
# Scribe and quality personas ensure completeness and accuracy

Knowledge Base Creation

/docs:index . --type docs
# Interactive knowledge base generation with project-specific patterns
# Architect persona provides structural organization and cross-referencing

Boundaries

Will:

• Generate comprehensive project documentation with intelligent organization and cross-referencing
• Apply multi-persona coordination for systematic analysis and quality validation
• Provide framework-specific patterns and established documentation standards

Will Not:

• Override existing manual documentation without explicit update permission
• Generate documentation without appropriate project structure analysis and validation
• Bypass established documentation standards or quality requirements

Reference: teacher

/docs:teacher - Concept Explanations & Learning Paths

Triggers

• Requests for clear explanations of complex programming concepts
• Educational content for algorithms or system behavior
• Learning path design and progressive skill development
• Structured exercises to verify understanding

Usage

/docs:teacher [topic] [--level beginner|intermediate|advanced] [--format lesson|path|exercise]

Behavioral Flow

1. Assess: Determine learner baseline and prerequisites 2. Explain: Break down concepts with clear, practical examples 3. Practice: Provide exercises and guided application 4. Verify: Validate understanding with checkpoints and summaries

Key behaviors:

• Teach understanding, not memorization
• Provide multiple explanation angles
• Always include practical examples

Delegation Protocol

When to delegate (use Task tool):

• ✅ Multi-topic learning paths
• ✅ Extensive tutorial sets or curricula
• ✅ Large exercise banks

Available subagents:

• learning-guide: Concept explanation, learning paths, exercises

Delegation strategy:

<function_calls>
<invoke name="Task">
  <subagent_type>learning-guide</subagent_type>
  <description>Develop a learning guide for the requested topic</description>
  <prompt>
    Build a learning guide with:
    - Concept breakdown
    - Progressive examples
    - Exercises and checkpoints
    - Verification questions
  </prompt>
</invoke>
</function_calls>

When NOT to delegate (use direct tools):

• ❌ Short explanations or small snippets
• ❌ Single function or concept notes

Tool Coordination

• Task tool: Delegates to learning-guide for full learning plans
• Read: Reference source material
• Write: Generate lesson or exercise content

Examples

Concept Explanation

/docs:teacher "async/await" --level beginner --format lesson

Learning Path

/docs:teacher "distributed systems" --format path --level intermediate

Exercises

/docs:teacher "binary search" --format exercise

Boundaries

Will:

• Provide clear educational explanations with exercises
• Build learning paths with progressive skill development

Will Not:

• Provide answers without explanation or context
• Skip prerequisites that are necessary for comprehension

Reference: tutorials

/docs:tutorials - Hands-On Tutorial Builder

Triggers

• Requests for step-by-step tutorials or workshops
• Hands-on learning content for frameworks or features
• Guides needing exercises, checkpoints, and troubleshooting
• Multi-part workshop or deep-dive tutorial plans

Usage

/docs:tutorials [topic] [--format quickstart|deep-dive|workshop|cookbook] [--level beginner|intermediate|advanced]

Behavioral Flow

1. Define: Learning objectives, prerequisites, and outcomes 2. Design: Break topics into progressive, runnable steps 3. Build: Create exercises, challenges, and validation checkpoints 4. Deliver: Provide troubleshooting, tips, and next steps

Key behaviors:

• Show, then explain
• Include runnable examples and expected output
• Add checkpoints and error recovery guidance

Delegation Protocol

When to delegate (use Task tool):

• ✅ Multi-part tutorials or workshop series
• ✅ Tutorials with >10 steps or multiple tracks
• ✅ Content requiring multiple learning styles

Available subagents:

• tutorial-engineer: Tutorial structure, exercises, troubleshooting, and formatting

Delegation strategy:

<function_calls>
<invoke name="Task">
  <subagent_type>tutorial-engineer</subagent_type>
  <description>Generate a full tutorial for the requested topic</description>
  <prompt>
    Create a tutorial with:
    - Objectives, prerequisites, and time estimate
    - Progressive steps with runnable code
    - Exercises, checkpoints, and troubleshooting
    - Summary and next steps
  </prompt>
</invoke>
</function_calls>

When NOT to delegate (use direct tools):

• ❌ Small quickstart with <5 steps
• ❌ Minor edits to existing tutorials

Tool Coordination

• Task tool: Delegates to tutorial-engineer for full tutorial creation
• Read: Ingest specs or existing docs
• Write: Deliver tutorial content in Markdown

Examples

Quick Start

/docs:tutorials "Build a REST API in FastAPI" --format quickstart

Deep Dive

/docs:tutorials "React Server Components" --format deep-dive --level advanced

Workshop Series

/docs:tutorials "Kubernetes fundamentals" --format workshop --level beginner

Boundaries

Will:

• Produce hands-on tutorials with exercises and checkpoints
• Add troubleshooting guidance and validation steps

Will Not:

• Ship tutorials without runnable examples
• Skip prerequisite setup steps when required

Writing Process & Style

Reference for producing clear, well-structured technical documentation tailored to specific audiences.

Audience Analysis Framework

Persona Mapping

Identify who will read the documentation before writing a single line.

Skill Level Assessment

• Beginner: Needs every step spelled out, definitions for domain terms, screenshots or examples at each stage
• Intermediate: Familiar with basics, needs task-specific guidance, appreciates shortcuts and tips
• Advanced: Wants reference-style content, edge cases, configuration options, and API surface details
• Mixed audience: Use progressive disclosure -- lead with essentials, layer depth in expandable sections or linked pages

Goal Identification Checklist

• [ ] What task does the reader need to complete?
• [ ] What do they already know?
• [ ] What information is blocking them?
• [ ] What is their next step after reading?

Documentation Types and Structures

API Documentation

# Resource Name
One-line description of what this endpoint/module does.

## Authentication
Required credentials or tokens.

## Endpoints / Methods
### METHOD /path
- Description
- Parameters (table: name, type, required, description)
- Request example
- Response example (success + error)
- Error codes

## Rate Limits
## Changelog

User Guide

# Guide Title
Brief description and who this is for.

## Prerequisites
What the reader needs before starting.

## Steps
### Step 1: [Action verb] [Object]
Explanation, then command or action, then verification.

### Step 2: ...

## Next Steps
Where to go after completing this guide.

## Troubleshooting
Common issues and resolutions.

Tutorial

# Tutorial: [What you'll build/learn]
Outcome statement and time estimate.

## What You'll Learn
Bulleted list of skills or concepts.

## Prerequisites
## Setup
## Part 1: [First concept]
  Explanation → Example → Practice
## Part 2: [Building on Part 1]
  ...
## Summary
## Exercises
## Further Reading

Changelog

# Changelog

## [version] - YYYY-MM-DD
### Added
### Changed
### Fixed
### Removed
### Deprecated

Troubleshooting Guide

# Troubleshooting: [System/Feature]

## Symptom: [What the user sees]
**Cause**: Why this happens.
**Fix**: Step-by-step resolution.
**Verify**: How to confirm the fix worked.

Style Patterns

Active Voice

Scanning-Friendly Structure

• Lead with the most important information (inverted pyramid)
• Use descriptive headings that tell the reader what they will get
• Keep paragraphs to 3-5 sentences maximum
• Use bullet lists for sets of items, numbered lists for sequences
• Bold key terms on first use
• Use tables for structured comparisons
• Add code blocks for anything the reader will type or reference

Progressive Disclosure

1. Surface layer: One-sentence summary of what and why 2. Action layer: Steps to complete the task 3. Detail layer: Options, edge cases, background context 4. Reference layer: Full API surface, configuration matrix, related topics

Terminology Consistency

• Pick one term per concept and use it everywhere
• Define abbreviations on first use
• Maintain a glossary for projects with heavy domain vocabulary
• Never alternate between synonyms for the same thing

Editing Checklists

Accuracy

• [ ] All commands and code samples tested and working
• [ ] Version numbers and paths match the current release
• [ ] Links resolve to valid destinations
• [ ] Screenshots match the current UI
• [ ] Error messages and outputs are accurate

Clarity

• [ ] Every sentence has a clear subject and verb
• [ ] No jargon used without definition
• [ ] Instructions are unambiguous (one way to interpret each step)
• [ ] Pronouns have obvious antecedents
• [ ] No assumptions about reader knowledge beyond stated prerequisites

Completeness

• [ ] Prerequisites listed before procedures
• [ ] Every step includes a verification method
• [ ] Error cases and edge cases documented
• [ ] Next steps or related topics linked
• [ ] All placeholders replaced with real values or clearly marked

Accessibility

• [ ] Headings follow a logical hierarchy (no skipped levels)
• [ ] Images have alt text describing their content
• [ ] Color is not the sole way to convey meaning
• [ ] Code blocks are labeled with the language
• [ ] Tables have header rows
• [ ] Links use descriptive text (not "click here")

Documentation Lifecycle

1. Drafting

• Identify audience, type, and scope
• Gather source material (code, specs, interviews, existing docs)
• Outline structure using the appropriate template
• Write first draft focusing on completeness over polish

2. Review

• Self-edit using the checklists above
• Technical review: subject-matter expert verifies accuracy
• Editorial review: check voice, structure, and readability
• Usability review: can someone follow the steps cold?

3. Publish

• Place in the correct location within the docs hierarchy
• Update indexes, navigation, and cross-references
• Add metadata (title, description, last-updated date)
• Verify rendering in the target format (site, PDF, IDE)

4. Maintain

• Set a review cadence (quarterly or per-release)
• Monitor for broken links and outdated references
• Track reader feedback and support tickets referencing docs
• Archive or redirect deprecated content rather than deleting

Template Patterns

Prerequisite Block

## Prerequisites

Before you begin, make sure you have:
- [Tool] version [X.Y] or later ([installation guide](link))
- [Access/credential] for [service]
- Familiarity with [concept] ([primer](link) if needed)

Step With Verification

### Step N: [Action verb] [Object]

[Brief explanation of what this does and why.]

\`\`\`sh
command --flag value
\`\`\`

Verify it worked:

\`\`\`sh
check-command
\`\`\`

Expected output:
\`\`\`
success indicator
\`\`\`

Admonition Patterns

> **Note**: Supplementary information that helps but isn't required.

> **Tip**: Shortcut or best practice the reader may not know.

> **Warning**: Action that could cause data loss or downtime.

> **Important**: Critical information the reader must not skip.

Decision Table

| If you need... | Use... | See... |
| --- | --- | --- |
| Quick start | Getting Started guide | [link] |
| Full API surface | API Reference | [link] |
| Migration help | Migration Guide | [link] |