docs

Docs — Documentation Generation & Maintenance

Activate When

• User invokes /godmode:docs
• User says "generate docs", "document this", "write a README"
• User asks for runbooks, API docs, or onboarding guides
• Shipping skill detects undocumented public APIs
• User says "are our docs up to date?" or "check documentation"

Workflow

Step 1: Determine Documentation Scope

Identify what documentation is needed:

SCOPE DETECTION:
- API: Generate OpenAPI/Swagger specs or endpoint documentation
- CODE: Generate JSDoc, docstrings, type annotations, inline comments
- README: Generate or update project/module README files
- RUNBOOK: Create operational runbooks for deployment, incidents, maintenance
- AUDIT: Check existing docs for staleness, gaps, and quality issues
- ALL: Full documentation sweep

Step 2: Inventory Existing Documentation

Survey the current state:

# Find existing documentation files
find . -name "*.md" -not -path "./node_modules/*" -not -path "./.git/*" | sort

# Find OpenAPI/Swagger specs
find . -name "openapi*" -o -name "swagger*" | head -20

Present inventory:

DOCUMENTATION INVENTORY:
  Documentation Status
| Category | Count | Coverage |
|--|--|--|
| README files | 3 | root, api, shared |
| API docs | 1 | OpenAPI 3.0 (partial) |
| Code docs | 47/120 | 39% of public exports |
| Runbooks | 0 | None |
| Architecture docs | 2 | ADRs only |
| Guides | 1 | Getting started |

Step 3: Generate API Documentation

For REST APIs, generate or update OpenAPI spec:

# Scan routes/controllers for endpoints
# For each endpoint, generate:
openapi: "3.0.3"
info:
  title: <API name>
  version: <version>

For each endpoint:

1. Read the route definition and handler
2. Extract request parameters, body schema, and response shape
3. Identify authentication requirements from middleware
4. Document error responses from error handling code
5. Add examples from test fixtures when available

Step 4: Generate Code Documentation

Analyze code and add documentation: