docs-create

Create Documentation

CRITICAL RULES

1. Analyze code before writing. Read the actual source code first. Never write documentation based on assumptions.
2. Bottom-up approach. Start from code structure, then build documentation that reflects reality.
3. Confirm scope with user. Present what will be documented before generating.
4. Never enter plan mode. Execute immediately.

Step 1: Analyze Target

Determine what to document from $ARGUMENTS:

• If a file/directory path: scan the code structure
• If a class/module name: find it in the codebase
• If no target: scan the entire project

# Discover project structure
find [target] -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.rs" -o -name "*.go" -o -name "*.java" \) | head -50

Identify:

• Language & framework (from package.json, Cargo.toml, pyproject.toml, etc.)
• Key modules (entry points, API routes, core business logic)
• Existing docs (README, docstrings, JSDoc, rustdoc, etc.)
• Public API surface (exports, endpoints, CLI commands)

Step 2: Confirm Documentation Plan

Present the plan and ask for approval. The documentation dimensions are grouped into 5 fasce. The user can pick one dimension, several (combined into a single artifact with sections), an entire fascia, or --full for everything.

Documentation plan for: [target]

Language: [detected]
Framework: [detected]

Files to document:
- [file1] -- [type: API endpoint / class / module / ORM model / config / etc.]
- [file2] -- [type]
- ...

Documentation dimensions (pick one or more; can also pick a whole fascia):

SURFACE (what the system exposes)
- [ ] interfaces       -- HTTP/REST, gRPC, GraphQL, WebSocket, CLI, library exports, events emitted (Kafka topics, RabbitMQ exchanges, webhooks emitted)
- [ ] config           -- env vars, config files, feature flags, secrets references, runtime profiles
- [ ] integrations     -- webhooks consumed, third-party APIs called, message queues, scheduled jobs/cron

INTERNALS (what the system is)
- [ ] architecture     -- layers, bounded contexts, component boundaries, design decisions (ADR-style)
- [ ] data-model       -- entities, DB schema, DTO/Pydantic/Zod/dataclass, ER diagram, constraints, indexes, migrations
- [ ] data-flows       -- request lifecycle, data pipelines, event flows, sequence diagrams, sagas
- [ ] state-machines   -- FSMs, lifecycle of domain objects, allowed transitions
- [ ] dependencies     -- internal module-to-module call graph + external libraries (with versions) + external services / SaaS
- [ ] concurrency      -- workers, queues, schedulers, async tasks, locking, idempotency
- [ ] glossary         -- ubiquitous language, domain terminology, business rules

OPERATIONS (how the system runs)
- [ ] auth             -- authn/authz flows, RBAC/ABAC, secrets management, PII handling, threat surface
- [ ] errors           -- error catalog, retry policy, circuit breaker, fallback, idempotency boundaries
- [ ] observability    -- logs emitted, metrics exposed, traces, alerts, referenced dashboards
- [ ] deployment       -- Docker/K8s/Terraform, CI/CD, environments, DNS/networking, operational runbooks

PROCESS (how the system evolves)
- [ ] build-release    -- versioning, changelog, release cadence, hot-fix process
- [ ] testing          -- test pyramid, fixtures, mocks, coverage gaps
- [ ] migrations       -- upgrade paths, breaking changes, deprecation cycle

CROSS-CUTTING
- [ ] performance      -- SLA/SLO, latency, throughput, known bottlenecks
- [ ] compliance       -- GDPR/PCI/HIPAA/SOC2 controls visible in code

TARGETED
- [ ] component        -- deep dive on a single module/class (zoom)

FULL
- [ ] full             -- all of the above, indexed with table of contents

Output: [format] at [output path]

1. Proceed with this plan
2. Adjust scope -- I'll tell you what to change
3. Cancel