Documentation Skill
Purpose
Generate documentation artifacts from implemented code. Create durable external context that survives beyond the current session.
When to Use
Mandatory (Always Run)
Documentation is mandatory for all spec-based workflows (oneoff-spec and orchestrator). Run after security review, before commit.
What to Document (scope varies by change)
- Public API additions: Full API docs (endpoints, methods, interfaces)
- User-facing features: User-oriented docs for features end users interact with
- Substantial changes: Architecture docs for multi-file implementations, new services
- Complex logic: Explanatory docs for non-obvious algorithms or workflows
- Configuration options: Document new environment variables or settings
- Bug fixes / minor changes: Lightweight docs (update existing docs if behavior changed, or a brief changelog entry)
Skip (docs step still runs but produces minimal output)
- Documentation-only changes (already documented)
- Trivial single-line fixes within oneoff-vibe (docs not dispatched for oneoff-vibe)
Documentation Types
API Documentation
For public endpoints and methods:
## 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:
## 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:
## 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
# 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.
# 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
docs/
├── 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: Generate Diagrams
Run the diagram generator to ensure all Mermaid diagrams are fresh:
node .claude/scripts/docs-generate.mjs
This produces .mmd files in .claude/docs/structured/generated/ for all available YAML sources (architecture, flows, ERD, state, security, deployment, C4 component). Missing sources are skipped silently.
Step 5.5: Phase 2 PRD Report Enrichment (AC-6.5)
When spec authoring is complete for a linked PRD, trigger Phase 2 enrichment of the PRD Report:
- Check for linked PRD: Look for
prdreference inmanifest.json - If PRD exists and Phase 1 report was generated:
- Dispatch documenter agent for Phase 2 assembly
- Documenter reads Phase 1 report, generates fresh diagrams, and enriches with:
- ERD diagrams from
data-models.yaml - Detailed sequence diagrams from spec flow definitions
- Contract overview table from wire protocol contracts
- ERD diagrams from
- Phase 2 retains all Phase 1 content
- Partial enrichment is acceptable: skip diagrams whose spec artifacts are unavailable, log reasons
- If no PRD linked: Skip Phase 2 (no action)
- Output: Enriched PRD Report at
.claude/prds/<prd-id>/report.mdusing template at.claude/templates/prd-report.template.md
Step 6: Validate
# Check code examples compile (if applicable)
npx tsc --noEmit docs/examples/*.ts
# Ensure consistent formatting
npx prettier --check docs/**/*.md
Step 7: Update Manifest
Update manifest.json with documentation status:
{
"convergence": {
"docs_generated": true
},
"decision_log": [
{
"timestamp": "<ISO timestamp>",
"actor": "agent",
"action": "docs_generated",
"details": "API docs + user guide created, 3 examples verified"
}
]
}
Add documentation log to spec group:
## 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.
| Category | When Required | Contents | | -------------------------------- | --------------------------- | ------------------------------------------------------------------------ | | High-Level Overview | All projects | Project purpose, quick start, workspace listing | | System Architecture | Multi-component projects | Data flow diagrams, service boundaries, component relationships | | API Documentation - Public | Projects with public APIs | Endpoints, authentication, request/response examples, error codes | | API Documentation - Internal | Projects with internal APIs | Internal endpoints, service-to-service contracts | | Operations Guide | Production systems | Deployment procedures, monitoring, troubleshooting, emergency procedures | | Frontend Documentation | UI projects | Component overview, state management, routing, key patterns | | Setup/Installation | All projects | Environment setup, dependencies, local development | | Contributing Guide | Shared/open projects | Branch strategy, PR process, code review expectations |
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:
- Be syntactically correct
- Use real types/imports from the codebase
- Demonstrate the happy path
- Be copy-paste runnable (with minimal setup)
Bad:
const result = doThing(params); // params undefined
Good:
import { AuthService } from '@/services/auth';
const authService = new AuthService();
const result = await authService.logout();
// result: { success: true }
Document Behavior, Not Implementation
Bad (leaks implementation):
The logout method clears the localStorage key 'auth_token'
and sets the BehaviorSubject to false.
Good (describes behavior):
The logout method ends the current session and redirects
to the login page. Any cached credentials are cleared.
Match Audience to Doc Type
| Doc Type | Audience | Tone | Detail Level | | ------------- | ------------------ | ---------------------- | ------------ | | API Reference | Developers | Technical, precise | High | | User Guide | End users | Friendly, task-focused | Medium | | Architecture | Future maintainers | Explanatory | High |
Output Format
## 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.docs_generated: true
Integration with Other Skills
Before docs:
/securityreview passed
After docs:
- Ready for commit/merge
Documentation is typically the final step before commit for substantial changes.
Structured Documentation Nudge (AC-10.1, AC-10.2)
After generating documentation artifacts, check whether the implementation touched modules defined in the project's structured documentation system.
How to Check
- Read architecture.yaml: If
.claude/docs/structured/architecture.yamlexists, read it to get the list of modules and theirpathglobs. - Identify touched files: Use
git diff --name-onlyor the spec's Implementation Evidence to get the list of files modified in this session. - Match files to modules: For each modified file, check if it falls within any module's
pathglob pattern. - Check for doc updates: For each matched module, check if
architecture.yamlor any relevant flow files (in.claude/docs/structured/flows/) were also modified in this session. - Emit nudge if needed: If implementation files within a module's scope were modified but the structured docs were NOT updated, emit a nudge message.
Nudge Format
When structured docs may need updating, include this in your output:
### Structured Documentation Review
The following modules had implementation changes but no corresponding structured doc updates:
- **module-name**: Files matching `path/glob/**` were modified
- Consider: Update architecture.yaml description or responsibilities
- Consider: Add/update flow steps if behavior changed
- Consider: Add new glossary terms if new concepts introduced
Run `node .claude/scripts/docs-validate.mjs` to check for cross-reference issues.
When to Skip
- If
.claude/docs/structured/architecture.yamldoes not exist (structured docs not adopted) - If no implementation files match any module's path glob
- If the structured docs were already updated in this session
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:
# 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:
# 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:
# 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