spec-kitty

Documentation Mission Guide

This guide covers the Documentation Kitty mission, which helps you create and maintain high-quality software documentation following Write the Docs and Divio principles.

Overview

The Documentation Mission provides a structured workflow for generating comprehensive documentation across four distinct types (Divio system), with automated gap analysis and support for API reference generation from code.

Key Features:

Divio 4-type system: Distinct documentation for tutorials, how-tos, reference, and explanations
Iteration modes: Support for initial documentation, gap-filling, and feature-specific docs
Generator integration: Automatic API reference generation (JSDoc, Sphinx, rustdoc)
Gap analysis: Identify missing documentation and prioritize by user impact
Documentation as code: Version-controlled docs living alongside source code

Quick Start

Initial Documentation (New Project)

Create comprehensive documentation for a new project:

# In your project root
cd kitty-specs/
/spec-kitty.specify Create comprehensive documentation for our project, covering all four Divio types

When prompted, specify:

Iteration mode: initial
Divio types: tutorial, how-to, reference, explanation
Target audience: developers (or end-users, contributors, operators)
Generators: Choose based on your project language (e.g., sphinx for Python)

Then proceed with planning and implementation:

/spec-kitty.plan We'll use Sphinx for Python API docs, organize by feature modules
/spec-kitty.tasks
/spec-kitty.implement

Gap-Filling Mode (Existing Documentation)

Identify and fill gaps in existing documentation:

/spec-kitty.specify Audit existing documentation and fill identified gaps

When prompted:

Iteration mode: gap_filling
Divio types: Leave blank to analyze all types
Target audience: Match your existing docs

The mission will:

Scan your docs/ directory
Classify existing docs by Divio type
Build a coverage matrix
Prioritize missing documentation
Generate tasks to fill high-priority gaps

Feature-Specific Documentation

Document a specific feature or component:

/spec-kitty.specify Document the new authentication system

When prompted:

Iteration mode: feature_specific
Divio types: Choose relevant types (e.g., how-to, reference for API features)
Target audience: Match your users

Workflow Phases

The Documentation Mission follows a six-phase workflow:

1. Discover

Purpose: Identify documentation needs and target audience

Activities:

Define target audience (developers, end-users, contributors, operators)
Choose iteration mode (initial, gap-filling, feature-specific)
Select Divio types to include
Identify documentation gaps (if gap-filling mode)

Artifacts Created:

spec.md - Documentation requirements and scope

2. Audit

Purpose: Analyze existing documentation and identify gaps

Activities:

Detect documentation framework (Sphinx, MkDocs, Docusaurus, etc.)
Classify existing docs by Divio type
Build coverage matrix showing what exists
Identify missing documentation
Prioritize gaps by user impact

Artifacts Created:

gap-analysis.md - Comprehensive audit report with coverage matrix

Gap Analysis Output Example:

## Coverage Matrix

| Area | tutorial | how-to | reference | explanation |
|------|----------|--------|-----------|-------------|
| auth | ✓        | ✗      | ✓         | ✗           |
| api  | ✗        | ✓      | ✓         | ✗           |
| cli  | ✓        | ✓      | ✗         | ✗           |

**Coverage**: 6/12 cells = 50.0%

## Identified Gaps

### High Priority
- **auth → how-to**: Users need how-tos to solve common problems and tasks
- **cli → reference**: Users need API reference to use core features

### Medium Priority
- **api → tutorial**: Users need tutorials for advanced features

3. Design

Purpose: Plan documentation structure and select generators

Activities:

Design documentation hierarchy and navigation
Configure generators for API reference docs
Plan Divio templates for each selected type
Define gap-filling strategy (if iterating)

Artifacts Created:

plan.md - Documentation structure and generator config
divio-templates/ - Template files for each Divio type
generator-configs/ - Configuration for JSDoc/Sphinx/rustdoc

4. Generate

Purpose: Create documentation from templates and generators

Activities:

Populate Divio templates with project-specific content
Invoke generators to produce API reference docs
Create tutorial walkthroughs
Write how-to guides for common tasks
Generate explanation docs for architecture/concepts

Artifacts Created:

Documentation files in docs/ directory
Generated API reference (e.g., docs/api/python/)

5. Validate

Purpose: Check quality, accessibility, and completeness

Activities:

Verify Divio type adherence (each doc follows its type’s purpose)
Check accessibility guidelines (headings, alt text, clear language)
Assess generator output quality
Test documentation builds (Sphinx/MkDocs/etc.)
Review for bias-free, inclusive language

Validation Checks:

All selected Divio types have content
No conflicting generators (one per language)
Templates are populated (no placeholders)
Gap analysis complete (if gap-filling mode)

6. Publish

Purpose: Deploy documentation and notify stakeholders

Activities:

Build final documentation site
Deploy to hosting (Read the Docs, GitHub Pages, etc.)
Update project README with docs link
Notify team of new documentation

Artifacts Created:

publish.md - Deployment record and access URLs

Divio Documentation System

The mission uses the Divio 4-type documentation system, where each type serves a distinct purpose:

Tutorial

Purpose: Learning-oriented, teaches a beginner

Characteristics:

Step-by-step walkthrough
Assumes no prior knowledge
Teaches by doing (hands-on)
Provides complete, working example
Builds confidence and familiarity

Example Structure:

# Getting Started with [Project]

## What You'll Build
By the end of this tutorial, you'll have a working...

## Prerequisites
- Python 3.11+
- Basic command line knowledge

## Step 1: Installation
First, install the package...

## Step 2: Your First [Feature]
Now let's create...

## Next Steps
You've learned the basics. Next, explore...

When to Use:

Onboarding new users
Teaching core workflows
Building initial confidence
Demonstrating value quickly

How-To Guide

Purpose: Task-oriented, solves a specific problem

Characteristics:

Focused on a single task or problem
Assumes some familiarity
Shows how to achieve a goal
Lists prerequisites
Includes verification steps

Example Structure:

# How to Configure OAuth Authentication

## Problem
You need to add OAuth authentication to your application.

## Prerequisites
- Existing application setup
- OAuth provider credentials

## Solution

### Step 1: Install Dependencies
```bash
pip install authlib

Step 2: Configure Provider

…

Verification

Test your OAuth flow by…

Troubleshooting

Error: Invalid redirect URI - Check your… ```

When to Use:

Solving specific problems
Addressing common user questions
Guiding experienced users
Providing recipes for tasks

Reference

Purpose: Information-oriented, describes the API

Characteristics:

Comprehensive and authoritative
Describes what exists
Organized for lookup (not learning)
Technical and precise
Often auto-generated from code

Example Structure:

# API Reference

## Module: authentication

### Function: `validate_token(token: str) -> bool`

Validates an authentication token.

**Parameters**:
- `token` (str): The JWT token to validate

**Returns**:
- `bool`: True if valid, False otherwise

**Raises**:
- `TokenExpiredError`: If token has expired
- `InvalidSignatureError`: If signature verification fails

**Example**:
```python
is_valid = validate_token("eyJ0eXAiOiJKV1QiLCJh...")

**When to Use**:
- Documenting all APIs
- Providing lookup information
- Supporting experienced users
- Generating from code comments

### Explanation

**Purpose**: Understanding-oriented, explains concepts

**Characteristics**:
- Discusses why, not how
- Provides background and context
- Explains architecture and design
- Explores alternatives and trade-offs
- Deepens understanding

**Example Structure**:
```markdown
# Authentication Architecture

## Why Token-Based Authentication?

Traditional session-based authentication...

## How It Works

When a user logs in, the system...

[Architecture diagram]

## Design Decisions

### Why JWT Over Session Cookies?

We chose JWT tokens because...

**Trade-offs**:
- ✓ Stateless (scales horizontally)
- ✓ Works across domains
- ✗ Cannot revoke individual tokens
- ✗ Larger payload than session ID

### Alternative Approaches Considered

We also evaluated...

## Security Considerations

Token-based authentication introduces...

When to Use:

Explaining architecture
Discussing design decisions
Providing background concepts
Helping users understand “why”

Generator Usage

The mission supports three API reference generators:

JSDoc (JavaScript/TypeScript)

Detection: Automatically enabled if project contains:

package.json file
.js, .jsx, .ts, or .tsx files

Configuration:

{
  "source": {
    "include": ["src/"],
    "includePattern": ".+\\.(js|jsx|ts|tsx)$"
  },
  "opts": {
    "destination": "docs/api/javascript",
    "recurse": true,
    "template": "node_modules/docdash"
  }
}

Setup:

Install JSDoc and template:
```
npm install --save-dev jsdoc docdash
```
Add JSDoc comments to your code: ```javascript /**
- Validates user credentials.
- @param {string} username - The username
- @param {string} password - The password
- @returns {Promise} True if valid
- @throws {AuthError} If authentication fails */ async function validateCredentials(username, password) { // Implementation… } ```
Generate docs:
```
npx jsdoc -c jsdoc.json
```

Output: HTML documentation in docs/api/javascript/

Sphinx (Python)

Detection: Automatically enabled if project contains:

setup.py or pyproject.toml file
.py files

Configuration (conf.py):

project = 'Your Project'
extensions = [
    'sphinx.ext.autodoc',      # Auto-generate from docstrings
    'sphinx.ext.napoleon',     # Google/NumPy style docstrings
    'sphinx.ext.viewcode',     # Link to source code
]

# Napoleon settings for Google-style docstrings
napoleon_google_docstring = True
napoleon_numpy_docstring = True

Setup:

Install Sphinx and theme:
```
pip install sphinx sphinx-rtd-theme
```

Add docstrings to your code:

def validate_token(token: str) -> bool:
    """Validate an authentication token.

    Args:
        token: The JWT token to validate

    Returns:
        True if valid, False otherwise

    Raises:
        TokenExpiredError: If token has expired
    """
    # Implementation...

Generate docs:

sphinx-build -b html docs/ docs/_build/html/

Output: HTML documentation in docs/_build/html/

rustdoc (Rust)

Detection: Automatically enabled if project contains:

Cargo.toml file
.rs files

Configuration (in Cargo.toml):

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--document-private-items"]  # Optional: include private APIs

Setup:

Add doc comments to your code:

/// Validates an authentication token.
///
/// # Arguments
///
/// * `token` - The JWT token to validate
///
/// # Returns
///
/// Returns `true` if valid, `false` otherwise
///
/// # Errors
///
/// Returns `TokenError` if token is expired or invalid
pub fn validate_token(token: &str) -> Result<bool, TokenError> {
    // Implementation...
}

Generate docs:

cargo doc --no-deps --target-dir docs/output/

Output: HTML documentation in docs/output/doc/

Iteration Modes

Initial Mode

Use Case: Creating documentation for a new project with no existing docs

Behavior:

No gap analysis performed
Creates complete documentation suite
All selected Divio types included
Generators configured from scratch

State Persisted:

{
  "iteration_mode": "initial",
  "divio_types_selected": ["tutorial", "how-to", "reference", "explanation"],
  "generators_configured": [
    {
      "name": "sphinx",
      "language": "python",
      "config_path": "docs/conf.py"
    }
  ],
  "target_audience": "developers",
  "last_audit_date": null,
  "coverage_percentage": 0.0
}

Gap-Filling Mode

Use Case: Iterating on existing documentation to fill identified gaps

Behavior:

Runs comprehensive gap analysis
Identifies missing Divio types per project area
Prioritizes gaps by user impact (HIGH/MEDIUM/LOW)
Focuses tasks on high-priority gaps
Updates coverage metadata after completion

State Persisted:

{
  "iteration_mode": "gap_filling",
  "divio_types_selected": [],  // Analyze all types
  "generators_configured": [...],  // Existing generators
  "target_audience": "developers",
  "last_audit_date": "2026-01-13T15:00:00Z",
  "coverage_percentage": 0.67  // 67% coverage after audit
}

Gap Prioritization Rules:

HIGH: Missing tutorials for core features (blocks new users)
HIGH: Missing reference for core APIs (users can’t find APIs)
MEDIUM: Missing how-tos for common tasks (users struggle)
MEDIUM: Missing tutorials for advanced features
LOW: Missing explanations (nice-to-have, not blocking)

Feature-Specific Mode

Use Case: Documenting a specific feature or component

Behavior:

Scoped to a single feature/module
Only includes relevant Divio types
Integrates with existing documentation structure
May trigger partial gap analysis for the feature

State Persisted:

{
  "iteration_mode": "feature_specific",
  "divio_types_selected": ["how-to", "reference"],  // Only relevant types
  "generators_configured": [...],
  "target_audience": "developers",
  "last_audit_date": "2026-01-13T15:00:00Z",
  "coverage_percentage": 0.75  // Project-wide coverage
}

Troubleshooting

Generator Not Found

Error: GeneratorError: sphinx-build not found - install Sphinx to use this generator

Solution: Install the required generator tool:

# Sphinx (Python)
pip install sphinx sphinx-rtd-theme

# JSDoc (JavaScript)
npm install --save-dev jsdoc docdash

# rustdoc (Rust) - comes with Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Configuration File Not Found

Error: conf.py not found - run configure() first

Solution: The generator configuration step failed. Manually run:

# During /spec-kitty.plan phase
# Generator configuration should be created automatically
# If missing, check plan.md for generator setup instructions

Low Confidence Classification

Issue: Gap analysis shows low confidence for document types

Cause: Documents lack frontmatter with explicit type field

Solution: Add frontmatter to existing docs:

---
type: tutorial  # or how-to, reference, explanation
title: Getting Started
---

# Getting Started
...

Coverage Matrix Shows Gaps for Generated Docs

Issue: API reference docs exist but show as gaps

Cause: Auto-generated docs may not be in docs/ directory

Solution: Configure generator output paths to write to docs/api/:

# Sphinx conf.py
html_output = 'docs/api/python/'

# JSDoc config
"opts": {
  "destination": "docs/api/javascript"
}

Documentation Framework Not Detected

Issue: Gap analysis shows “unknown” framework

Solution: Add framework indicator file:

Sphinx: Create docs/conf.py
MkDocs: Create mkdocs.yml
Docusaurus: Create docusaurus.config.js
Plain Markdown: No action needed (detected automatically)

Validation Fails: Templates Not Populated

Error: Validation failed: templates_populated check failed

Cause: Template files contain placeholders like [TODO: ...]

Solution: Replace all placeholders with actual content:

# Before
## Prerequisites
[TODO: List prerequisites]

# After
## Prerequisites
- Python 3.11 or later
- pip package manager

Complete Examples

Example 1: Initial Project Documentation

Scenario: Document a new Python CLI tool from scratch

Step 1: Specify

/spec-kitty.specify Create comprehensive documentation for our CLI tool

Responses to prompts:

Iteration mode: initial
Divio types: tutorial, how-to, reference, explanation
Target audience: developers
Generators: sphinx

Step 2: Plan

/spec-kitty.plan
- Tutorial: Getting started guide showing installation and first command
- How-tos: Common tasks (configuring, deploying, troubleshooting)
- Reference: Full CLI command reference (auto-generated from argparse)
- Explanation: Architecture and design decisions
- Use Sphinx with autodoc for API reference
- Organize as docs/tutorial/, docs/howto/, docs/reference/, docs/explanation/

Step 3: Generate Tasks

/spec-kitty.tasks

Output includes work packages like:

WP01: Sphinx configuration and project setup
WP02: Tutorial content creation
WP03: How-to guides for common tasks
WP04: API reference generation
WP05: Explanation docs for architecture
WP06: Documentation build and validation

Step 4: Implement

/spec-kitty.implement

Agent creates:

docs/conf.py (Sphinx configuration)
docs/tutorial/getting-started.md
docs/howto/configuring.md, docs/howto/deploying.md
docs/reference/cli.md (generated from argparse)
docs/explanation/architecture.md
Updated README with docs link

Step 5: Review and Accept

/spec-kitty.review
/spec-kitty.accept

Result: Complete documentation suite ready for deployment

Example 2: Gap-Filling Existing Documentation

Scenario: Existing project has API reference but missing tutorials and how-tos

Step 1: Specify

/spec-kitty.specify Audit documentation and fill gaps

Responses to prompts:

Iteration mode: gap_filling
Divio types: (leave blank to analyze all)
Target audience: developers

Step 2: Gap Analysis

Automatic audit generates gap-analysis.md:

## Coverage Matrix

| Area | tutorial | how-to | reference | explanation |
|------|----------|--------|-----------|-------------|
| cli  | ✗        | ✗      | ✓         | ✗           |
| api  | ✗        | ✗      | ✓         | ✗           |
| auth | ✗        | ✗      | ✓         | ✗           |

**Coverage**: 3/12 cells = 25.0%

## Identified Gaps

### High Priority
- **cli → tutorial**: New users need tutorials to get started
- **api → tutorial**: New users need tutorials to get started
- **auth → tutorial**: New users need tutorials to get started

### Medium Priority
- **cli → how-to**: Users need how-tos to solve common problems
- **api → how-to**: Users need how-tos to solve common problems
- **auth → how-to**: Users need how-tos to solve common problems

Step 3: Plan

/spec-kitty.plan
Focus on high-priority gaps first:
- Tutorial for CLI: "Getting Started with CLI"
- Tutorial for API: "Building Your First Integration"
- Tutorial for Auth: "Implementing Authentication"
Then medium-priority:
- How-to for CLI: "Common CLI Tasks"
- How-to for API: "API Integration Patterns"
- How-to for Auth: "Configuring OAuth"

Step 4: Generate Tasks

Tasks focus on filling gaps:

WP01: CLI Getting Started tutorial
WP02: API integration tutorial
WP03: Authentication tutorial
WP04: CLI how-to guides
WP05: API how-to guides
WP06: Auth how-to guides

Step 5: Implement and Validate

After implementation, re-run gap analysis:

# In validate phase, gap analysis runs again
# New coverage: 9/12 cells = 75.0%

Result: High-priority gaps filled, documentation coverage improved from 25% to 75%

Additional Resources

Write the Docs Best Practices: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
Divio Documentation System: https://documentation.divio.com/
Sphinx Documentation: https://www.sphinx-doc.org/
JSDoc Documentation: https://jsdoc.app/
rustdoc Guide: https://doc.rust-lang.org/rustdoc/

State Management

Documentation state is persisted in kitty-specs/<feature>/meta.json under the documentation_state field. This enables:

Iteration tracking: Remember which mode (initial/gap-filling/feature-specific)
Configuration reuse: Persist generator configs across runs
Audit history: Track last audit date and coverage percentage
Divio type selection: Remember which types user chose

State is automatically managed during the workflow. No manual editing required.

Mission Configuration

The Documentation Mission is defined in src/specify_cli/missions/documentation/mission.yaml:

name: "Documentation Kitty"
domain: "other"
workflow:
  phases:
    - discover
    - audit
    - design
    - generate
    - validate
    - publish

artifacts:
  required:
    - spec.md
    - plan.md
    - tasks.md
    - gap-analysis.md
  optional:
    - divio-templates/
    - generator-configs/
    - audit-report.md
    - research.md

Mission-specific commands customize behavior:

/spec-kitty.specify prompts for iteration mode, Divio types, generators
/spec-kitty.plan prompts for documentation structure, generator configs
/spec-kitty.implement generates docs from templates and invokes generators
/spec-kitty.review validates Divio adherence, accessibility, completeness

Implementation Details

For contributors interested in the implementation:

Mission configuration: src/specify_cli/missions/documentation/mission.yaml
Gap analysis: src/specify_cli/gap_analysis.py
Generator implementations: src/specify_cli/doc_generators.py
State management: src/specify_cli/doc_state.py

These files are in the Spec Kitty source repository.

Try It

Claude Code Workflow

How-To Guides

Reference

This site is open source. Improve this page.

spec-kitty

Documentation Mission Guide

Overview

Quick Start

Initial Documentation (New Project)

Gap-Filling Mode (Existing Documentation)

Feature-Specific Documentation

Workflow Phases

1. Discover

2. Audit

3. Design

4. Generate

5. Validate

6. Publish

Divio Documentation System

Tutorial

How-To Guide

Step 2: Configure Provider

Step 3: Implement Login Flow

Verification

Troubleshooting

Reference

Generator Usage

JSDoc (JavaScript/TypeScript)

Sphinx (Python)

rustdoc (Rust)

Iteration Modes

Initial Mode

Gap-Filling Mode

Feature-Specific Mode

Troubleshooting

Generator Not Found

Configuration File Not Found

Low Confidence Classification

Coverage Matrix Shows Gaps for Generated Docs

Documentation Framework Not Detected

Validation Fails: Templates Not Populated

Complete Examples

Example 1: Initial Project Documentation

Example 2: Gap-Filling Existing Documentation

Additional Resources

State Management

Mission Configuration

Implementation Details

Try It

How-To Guides

Reference