---

name: docs description: Generate documentation from implementation. Creates user docs, API docs, and architecture docs. HIGHLY RECOMMENDED for substantial changes, especially public APIs. allowed-tools: Read, Write, Glob, Grep

Documentation Skill

Purpose

Generate documentation artifacts from implemented code. Create durable external context that survives beyond the current session.

When to Use

Highly Recommended (Should Use)

• Public API additions: New endpoints, methods, or interfaces
• User-facing features: Features end users will interact with
• Substantial changes: Multi-file implementations, new services
• Complex logic: Non-obvious algorithms or workflows
• Configuration options: New environment variables or settings

Optional

• Internal refactoring (no API changes)
• Bug fixes (unless they change documented behavior)
• Test-only changes
• Minor UI tweaks

Skip

• Documentation-only changes (already documented)
• Trivial single-line fixes

Documentation Types

API Documentation

For public endpoints and methods:

Copy## methodName

Brief description of what it does.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | Yes | What this parameter controls |

### Returns

`ReturnType` - Description of return value

### Errors

| Error | When |
|-------|------|
| InvalidInputError | When param1 is empty |

### Example

\`\`\`typescript
const result = await service.methodName('value');
\`\`\`

User Guides

For user-facing features:

Copy## Feature Name

What this feature does and why you'd use it.

### Getting Started

Step-by-step instructions for basic usage.

### Configuration

Available options and what they control.

### Examples

Common use cases with code/UI examples.

### Troubleshooting

Common issues and how to resolve them.

Architecture Documentation

For complex systems:

Copy## Component Name

### Purpose

Why this component exists and what problem it solves.

### Design Decisions

Key decisions and their rationale.

### Data Flow

How data moves through the component.

### Dependencies

What this component depends on and why.

Documentation Process

Step 1: Identify Scope

Copy# Check what was implemented from spec group
cat .claude/specs/groups/<spec-group-id>/manifest.json
cat .claude/specs/groups/<spec-group-id>/spec.md

# List atomic specs for implementation details
ls .claude/specs/groups/<spec-group-id>/atomic/

# Read atomic specs for Implementation Evidence (exact files/lines changed)
cat .claude/specs/groups/<spec-group-id>/atomic/as-001-*.md

# Find modified files from Implementation Evidence
# Or use git diff
git diff --name-only main..HEAD

# Identify public interfaces
grep -r "export" src/ --include="*.ts" | grep -E "(class|interface|function|const)"

Determine documentation needs:

• Public APIs → API docs (always)
• User-facing features → User guides (always)
• Internal architecture → Architecture docs (if complex)
• Configuration → Configuration docs (always)

Step 2: Read Implementation (Not Spec)

Critical: Document what the code DOES, not what the spec SAYS.

Copy# Read actual implementation
cat src/services/feature.ts

# Check for edge cases in tests
cat src/services/__tests__/feature.test.ts

# Look for error handling
grep -A5 "catch\|throw\|Error" src/services/feature.ts

Step 3: Generate Documentation

Follow documentation standards:

DO:

• Use present tense ("Returns" not "Will return")
• Include working code examples
• Document error conditions
• Link to related documentation
• Keep examples minimal but complete

DON'T:

• Copy spec language verbatim
• Document internal implementation details in user docs
• Assume reader knows the codebase
• Leave placeholder text ("TODO", "TBD")
• Over-document obvious things

Step 4: Place Documentation

Copydocs/
├── api/                 # API reference
│   └── services/
│       └── auth.md
├── guides/              # User guides
│   └── authentication.md
├── architecture/        # Internal architecture
│   └── auth-system.md
└── README.md            # Project overview

For inline documentation:

• JSDoc for public APIs
• README.md in package roots
• CHANGELOG.md for version history

Step 5: Validate

Copy# Check code examples compile (if applicable)
npx tsc --noEmit docs/examples/*.ts

# Ensure consistent formatting
npx prettier --check docs/**/*.md

Step 6: Update Manifest

Update manifest.json with documentation status:

Copy{
  "convergence": {
    "documentation_complete": true
  },
  "decision_log": [
    {
      "timestamp": "<ISO timestamp>",
      "actor": "agent",
      "action": "documentation_complete",
      "details": "API docs + user guide created, 3 examples verified"
    }
  ]
}

Add documentation log to spec group:

Copy## Documentation Log

- 2026-01-08: Documentation complete
  - API docs: docs/api/services/auth.md
  - User guide: docs/guides/authentication.md
  - Atomic specs documented: as-001, as-002, as-003
  - Examples verified: 3 code samples tested

Documentation Standards

Required Documentation Categories

Assess which categories apply to the project, then generate documentation for each applicable category.

Conditional Requirements:

• Frontend docs depth: For backend-heavy projects, frontend docs can be lighter. For frontend-heavy or balanced projects, frontend docs should match backend docs depth.
• "If applicable" rule: A category is required only if the project has that component (e.g., no API docs needed if no API exists)

Documentation Patterns

Follow these established patterns based on documentation type:

README Structure:

• Quick Start
• Scripts/Commands
• Environment/Configuration
• Project Structure (if complex)
• Troubleshooting

API Documentation Pattern:

• Table of contents
• Security/Authentication section
• Environment variables table
• Endpoints grouped by resource
• Request/response examples for each endpoint
• WebSocket documentation if applicable
• Error handling reference

Operations Guide Pattern:

• Quick reference table at top
• Step-by-step procedures
• Troubleshooting section with common issues
• Emergency procedures
• Configuration reference

Documentation Index Pattern:

• Serve as table of contents with categorized links
• Include terminology glossary for project-specific terms
• Cross-link related documents with "See Also" sections

Formatting Conventions

• H1 for title only, H2 for major sections
• Tables for structured data (env vars, endpoints, commands)
• Code blocks with language specifiers
• No emojis in documentation
• "See Also" sections for cross-references

Code Examples Must Work

Every code example must:

1. Be syntactically correct
2. Use real types/imports from the codebase
3. Demonstrate the happy path
4. Be copy-paste runnable (with minimal setup)

Bad:

Copyconst result = doThing(params); // params undefined

Good:

Copyimport { AuthService } from '@/services/auth';

const authService = new AuthService();
const result = await authService.logout();
// result: { success: true }

Document Behavior, Not Implementation

Bad (leaks implementation):

CopyThe logout method clears the localStorage key 'auth_token'
and sets the BehaviorSubject to false.

Good (describes behavior):

CopyThe logout method ends the current session and redirects
to the login page. Any cached credentials are cleared.

Match Audience to Doc Type

Output Format

Copy## Documentation Complete

**Spec Group**: .claude/specs/groups/<spec-group-id>/

**Atomic Specs Documented**:
- as-001: Logout Button UI
- as-002: Token Clearing
- as-003: Post-Logout Redirect

**Artifacts Created**:
- docs/api/services/auth.md (API reference)
- docs/guides/authentication.md (user guide)

**Coverage**:
- Public methods documented: 5/5
- Examples included: 3
- Error conditions documented: 4

**Validation**:
- Code examples: verified
- Links: verified
- Formatting: consistent

**Manifest Updated**: convergence.documentation_complete: true

Integration with Other Skills

Before docs:

• /security review passed

After docs:

• Ready for commit/merge

Documentation is typically the final step before commit for substantial changes.

Constraints

Read Implementation, Not Just Spec

The spec says what SHOULD happen. The code says what DOES happen. Document reality.

No Code Changes

You generate documentation only. If you find:

• Undocumented public APIs → Document them
• Bugs in implementation → Note in report, don't fix
• Missing error handling → Document current behavior, note gap

Consistency Over Creativity

Match existing documentation style in the project. Follow established patterns.

Examples

Example 1: API Documentation

Input: New logout endpoint implementation

Output:

Copy# AuthService.logout()

Terminates the current user session and clears authentication state.

## Signature

\`\`\`typescript
async logout(): Promise<void>
\`\`\`

## Behavior

1. Calls server to invalidate session
2. Clears local authentication token
3. Updates auth state to unauthenticated
4. Triggers redirect to login page

## Errors

| Error | Cause |
|-------|-------|
| `NetworkError` | Cannot reach server |
| `LogoutError` | Server rejected logout |

## Example

\`\`\`typescript
import { authService } from '@/services/auth';

try {
  await authService.logout();
  // User is now logged out, redirect handled automatically
} catch (error) {
  if (error instanceof NetworkError) {
    showToast('Check your connection and try again');
  }
}
\`\`\`

Example 2: User Guide

Input: New dashboard feature

Output:

Copy# Using the Dashboard

The dashboard provides an overview of your daily tasks and priorities.

## Getting Started

1. Log in to your account
2. Click "Dashboard" in the navigation menu
3. Your daily briefing appears automatically

## Features

### Daily Briefing
Shows your priorities for today, including:
- Urgent emails requiring response
- Upcoming calendar events
- Tasks due today

### Quick Actions
- **Snooze**: Postpone an item to later
- **Complete**: Mark a task as done
- **Delegate**: Assign to someone else

## Customization

Access Settings → Dashboard to configure:
- Briefing time (default: 9:00 AM)
- Priority thresholds
- Notification preferences

Example 3: Architecture Doc

Input: New notification service

Output:

Copy# Notification Service Architecture

## Purpose

Centralizes all user notifications across channels (email, SMS, push).

## Design Decisions

**Why a separate service?**
- Decouples notification logic from business logic
- Enables channel-agnostic notification requests
- Supports future channels without core changes

**Why queue-based?**
- Handles burst traffic gracefully
- Enables retry logic for failed deliveries
- Provides delivery tracking

## Data Flow

\`\`\`
Business Logic → NotificationService.send()
                         ↓
                   Queue (Redis)
                         ↓
              Channel Adapters (Email, SMS, Push)
                         ↓
                 Delivery Status → Database
\`\`\`

## Dependencies

- **Redis**: Message queue
- **Telnyx**: SMS delivery
- **SendGrid**: Email delivery
- **Firebase**: Push notifications