Wherever <arguments> appears below, substitute the text the user typed after the skill name.
Maintain Documentation
Use the documentation-engineer agent to audit and refactor existing documentation:
This command provides a comprehensive documentation management workflow:
What This Does
Audit Phase - Inventories all existing documentation and runs a per-dimension drift check against the actual codebase. For each dimension the audit reports added / removed / renamed / retyped items, not just generic "outdated content". See "Per-Dimension Drift Checks" below for the full matrix.
Planning Phase - Creates a refactoring plan to fix identified issues:
- Merge duplicate content
- Update outdated sections with surgical Edits (per dimension)
- Link or archive orphaned pages
- Fix broken references
- Add missing sections for undocumented dimensions
Interactive Decision - Asks if you want to execute the refactoring plan
Execution Phase (optional) - Applies refactoring with your approval:
- Reorganizes documentation structure
- Merges and consolidates content
- Updates references and links
- Verifies no content was lost
When to Use
Use this command when you need to:
- Perform quarterly documentation health checks
- Clean up docs after major codebase refactoring
- Fix scattered or duplicated documentation
- Prepare documentation before onboarding new team members
- Identify gaps in API documentation coverage
- Ensure documentation matches current implementation
Example Interactive Flow
Audit-only workflow (report without changes):
You: /docs-maintain --audit-only
Agent: I've inventoried your documentation. Found:
- 3 duplicate documentation files
- 5 outdated sections that don't match code
- 2 orphaned pages
- 1 broken link
[Detailed audit report provided]
Full refactoring workflow (audit -> plan -> execute):
You: /docs-maintain
Agent: I've inventoried your documentation. Found:
- 3 duplicate documentation files
- 5 outdated sections that don't match code
- 2 orphaned pages
- 1 broken link
Should I create a refactoring plan to fix these?
You: Yes
Agent: Here's the refactoring plan:
1. Merge UserAPI.md and user-api-reference.md -> api/users.md
2. Update 5 outdated sections to match current code
3. Link orphaned pages from main README or archive them
4. Fix broken link in README.md
Approve this plan?
You: Yes
Agent: Executing refactoring...
Done: Merged duplicate files
Done: Updated outdated sections
Done: Fixed orphaned pages
Done: Fixed broken links
Verification: All original content preserved, structure improved
Options/Flags
--audit-only - Generate audit report without creating refactoring plan or executing changes--plan-only - Generate refactoring plan without executing (stops after planning phase)--merge-duplicates - Focus specifically on identifying and merging duplicate content--scope <dim1,dim2,...> - Restrict audit to specific dimensions (e.g. --scope data-model,interfaces,dependencies); default is all dimensions[path] - Target specific folder or file (default: entire project)
Valid dimensions for --scope: interfaces, config, integrations, architecture, data-model, data-flows, state-machines, dependencies, concurrency, glossary, auth, errors, observability, deployment, testing, build-release, migrations, performance, compliance, component.
Examples:
/docs-maintain # Full workflow on entire project (all dimensions)
/docs-maintain --audit-only # Report only, no changes
/docs-maintain --plan-only # Audit + plan, no execution
/docs-maintain docs/ # Manage only docs/ folder
/docs-maintain README.md # Check specific file
/docs-maintain --merge-duplicates # Focus on duplicates
/docs-maintain --scope data-model # Schema drift only
/docs-maintain --scope interfaces,integrations,auth # API surface + integrations + auth drift
/docs-maintain --scope dependencies # Outdated package versions only
Issues Detected (generic)
The audit phase checks for these generic issues across all docs:
- Duplicate Documentation - Same topic documented in multiple files
- Broken Links - References to non-existent files or URLs
- Orphaned Pages - Documentation files not linked from any other docs
- Inconsistent Structure - Disorganized file hierarchy
- Stale Examples - Code examples that no longer work
Per-Dimension Drift Checks
In addition to the generic checks, the audit runs a structured drift check per dimension. For each one it compares the documented surface against the actual source of truth in the codebase and reports added / removed / renamed / retyped / signature-changed items, not just "outdated text".
| Dimension |
Source of truth in code |
Drift the audit reports |
interfaces |
Route definitions (FastAPI/Express/Spring/Django/Rails/Gin), CLI entry points (argparse, click, commander, clap), library __all__ / public exports, GraphQL SDL, gRPC .proto, emitted events (Kafka topics, RabbitMQ exchanges, webhook payloads) |
Endpoint added/removed, method/path changed, request or response schema changed, auth requirement changed, CLI flag added/removed, emitted event renamed or payload changed |
config |
Reads of os.environ / process.env / viper, dotenv templates, config file schemas, feature flag SDK calls |
Env var added/removed/renamed, default changed, required vs optional flip, feature flag added/removed |
integrations |
HTTP client calls to external hosts, webhook handlers, scheduled jobs (cron, APScheduler, BullMQ, Celery), message queue producers/consumers |
External API endpoint changed, new outbound dependency, webhook signature changed, cron schedule changed, queue topic renamed |
architecture |
Module structure, package boundaries, dependency direction |
New layer introduced, boundary violation now in code, component split or merged |
data-model |
ORM models (SQLAlchemy, Django ORM, Prisma, Drizzle, TypeORM, Sequelize, ActiveRecord, GORM, Diesel), Pydantic/Zod/dataclass, CREATE TABLE, migration files (Alembic, Flyway, Liquibase, Prisma migrate, knex) |
Entity added/removed/renamed, field added/removed/renamed, type changed, nullable flipped, default changed, FK or relationship changed, index added/removed |
data-flows |
Call sites between components, queue producers/consumers, event bus subscriptions, pipeline DAGs (Airflow, Prefect, Dagster) |
New flow path, removed/short-circuited path, new fan-out, ordering or transaction boundary changed |
state-machines |
Explicit FSM libs (xstate, transitions, statelessLib), enum-driven status fields with guarded transitions |
State added/removed/renamed, transition added/removed, guard changed, terminal state changed |
dependencies |
Package manifests (package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, Gemfile) + lockfiles + actual imports |
Dependency added/removed, version upgraded across major/minor, new optional dep, dep moved from prod to dev, unused dep, undeclared dep used |
concurrency |
Worker definitions, scheduler config, async runtime usage, lock primitives, idempotency keys |
Worker added/removed, queue topology changed, schedule changed, locking changed, retry/backoff policy changed |
glossary |
Domain types, enum names, value objects, repeated terminology in models/services |
Term renamed, term removed from code, new term used in code but absent from glossary |
auth |
Auth middleware, JWT/session config, RBAC tables, permission decorators, secret loaders |
New role/permission, removed role, scope change, secret source changed, MFA path added/removed |
errors |
Exception classes, error code enums, retry decorators, circuit-breaker config, idempotency keys |
Error code added/removed/renumbered, retry policy changed, new circuit breaker, idempotency boundary changed |
observability |
Logger calls with structured fields, metrics registrations (Prometheus/StatsD/OTel), tracer spans, alert rules |
Metric added/removed/renamed, log field renamed, span name changed, alert added/removed |
deployment |
Dockerfile, compose, k8s manifests, Helm charts, Terraform, CI workflows |
Image base changed, exposed port changed, env injection changed, healthcheck changed, new pipeline stage, runner changed |
testing |
Test directory structure, coverage config, fixtures, mocks |
New test layer, removed suite, coverage thresholds changed, fixture/mock signature changed |
build-release |
Version files, changelog generators, release scripts |
Version scheme changed, release pipeline changed, hot-fix branch convention changed |
migrations |
Migration history, deprecated APIs still referenced, @deprecated markers |
New breaking change not in migration guide, deprecated API removed, upgrade step now obsolete |
performance |
Benchmark scripts, load test configs, code-level perf budgets, SLO config |
SLO changed, benchmark removed, perf budget added/changed |
compliance |
Annotated PII fields, audit log calls, retention config, encryption usage |
New PII field undocumented, retention period changed, encryption algorithm changed |
component |
Single module/class under review |
Public API signature changed, internal helper now public or vice versa, dependency change |
Output
Audit-only mode produces:
- Comprehensive inventory of all documentation files
- Per-dimension drift report (added / removed / renamed / retyped items per dimension), with
**Source:** file:line citations to the code that is the source of truth
- Categorized list of generic issues (duplicates, broken links, orphaned, structural) with severity levels
- Recommendations for improvements
- No files modified
Full refactoring mode produces:
- All audit findings (generic + per-dimension)
- Detailed refactoring plan grouped by dimension, with proposed surgical Edits
- Executed changes with verification
- Summary of improvements made
- Confirmation that no content was lost
Quick Examples
# Quarterly documentation maintenance
/docs-maintain
# Quick health check without changes
/docs-maintain --audit-only
# Focus on cleaning up duplicates
/docs-maintain --merge-duplicates
# Manage API documentation only
/docs-maintain docs/api/
# Check if README is current
/docs-maintain README.md
Tips for Best Results
- Run audit-only first on large projects to understand scope before refactoring
- Target specific folders for large codebases to manage incrementally
- Review the plan carefully before approving execution
- Use version control - commit before running to easily review or revert changes
- Run after major refactors to keep docs in sync with code changes
- Schedule regularly - quarterly audits prevent documentation debt
Related Commands
/docs-create - Create NEW documentation from code analysis (use when docs don't exist)/docs-maintain - Audit and improve EXISTING documentation (use when docs exist but need maintenance)/humanize-docs - Rewrite existing docs to be more human-readable
1---2name: docs-maintain3description: Checks shipped documentation against the code and plans the fixes. TRIGGER WHEN: the user asks to audit, update, or verify existing technical docs against the current codebase, or to detect documentation drift on any of the 20 dimensions (endpoints removed but still documented, env vars renamed, schema fields added/dropped, dependencies upgraded, alerts removed, etc.). DO NOT TRIGGER WHEN: creating new docs from scratch (use /codebase-mapper:docs-create) or humanizing prose style (use /codebase-mapper:humanize-docs).4---56> Wherever `<arguments>` appears below, substitute the text the user typed after the skill name.78<!-- Generated by the Daodan compiler for codex. Edit the kernel, never this file. -->910# Maintain Documentation1112Use the `documentation-engineer` agent to audit and refactor existing documentation:1314<arguments>1516This command provides a comprehensive documentation management workflow:1718## What This Does19201. **Audit Phase** - Inventories all existing documentation and runs a **per-dimension drift check** against the actual codebase. For each dimension the audit reports added / removed / renamed / retyped items, not just generic "outdated content". See "Per-Dimension Drift Checks" below for the full matrix.21222. **Planning Phase** - Creates a refactoring plan to fix identified issues:23 - Merge duplicate content24 - Update outdated sections with surgical Edits (per dimension)25 - Link or archive orphaned pages26 - Fix broken references27 - Add missing sections for undocumented dimensions28293. **Interactive Decision** - Asks if you want to execute the refactoring plan30314. **Execution Phase** (optional) - Applies refactoring with your approval:32 - Reorganizes documentation structure33 - Merges and consolidates content34 - Updates references and links35 - Verifies no content was lost3637## When to Use3839Use this command when you need to:40- Perform quarterly documentation health checks41- Clean up docs after major codebase refactoring42- Fix scattered or duplicated documentation43- Prepare documentation before onboarding new team members44- Identify gaps in API documentation coverage45- Ensure documentation matches current implementation4647## Example Interactive Flow4849**Audit-only workflow** (report without changes):50```51You: /docs-maintain --audit-only5253Agent: I've inventoried your documentation. Found:54 - 3 duplicate documentation files55 - 5 outdated sections that don't match code56 - 2 orphaned pages57 - 1 broken link5859 [Detailed audit report provided]60```6162**Full refactoring workflow** (audit -> plan -> execute):63```64You: /docs-maintain6566Agent: I've inventoried your documentation. Found:67 - 3 duplicate documentation files68 - 5 outdated sections that don't match code69 - 2 orphaned pages70 - 1 broken link7172 Should I create a refactoring plan to fix these?73You: Yes7475Agent: Here's the refactoring plan:76 1. Merge UserAPI.md and user-api-reference.md -> api/users.md77 2. Update 5 outdated sections to match current code78 3. Link orphaned pages from main README or archive them79 4. Fix broken link in README.md8081 Approve this plan?82You: Yes8384Agent: Executing refactoring...85 Done: Merged duplicate files86 Done: Updated outdated sections87 Done: Fixed orphaned pages88 Done: Fixed broken links8990 Verification: All original content preserved, structure improved91```9293## Options/Flags9495- `--audit-only` - Generate audit report without creating refactoring plan or executing changes96- `--plan-only` - Generate refactoring plan without executing (stops after planning phase)97- `--merge-duplicates` - Focus specifically on identifying and merging duplicate content98- `--scope <dim1,dim2,...>` - Restrict audit to specific dimensions (e.g. `--scope data-model,interfaces,dependencies`); default is all dimensions99- `[path]` - Target specific folder or file (default: entire project)100101Valid dimensions for `--scope`: `interfaces`, `config`, `integrations`, `architecture`, `data-model`, `data-flows`, `state-machines`, `dependencies`, `concurrency`, `glossary`, `auth`, `errors`, `observability`, `deployment`, `testing`, `build-release`, `migrations`, `performance`, `compliance`, `component`.102103**Examples:**104```bash105/docs-maintain # Full workflow on entire project (all dimensions)106/docs-maintain --audit-only # Report only, no changes107/docs-maintain --plan-only # Audit + plan, no execution108/docs-maintain docs/ # Manage only docs/ folder109/docs-maintain README.md # Check specific file110/docs-maintain --merge-duplicates # Focus on duplicates111/docs-maintain --scope data-model # Schema drift only112/docs-maintain --scope interfaces,integrations,auth # API surface + integrations + auth drift113/docs-maintain --scope dependencies # Outdated package versions only114```115116## Issues Detected (generic)117118The audit phase checks for these generic issues across all docs:119120- **Duplicate Documentation** - Same topic documented in multiple files121- **Broken Links** - References to non-existent files or URLs122- **Orphaned Pages** - Documentation files not linked from any other docs123- **Inconsistent Structure** - Disorganized file hierarchy124- **Stale Examples** - Code examples that no longer work125126## Per-Dimension Drift Checks127128In addition to the generic checks, the audit runs a **structured drift check per dimension**. For each one it compares the documented surface against the actual source of truth in the codebase and reports added / removed / renamed / retyped / signature-changed items, not just "outdated text".129130| Dimension | Source of truth in code | Drift the audit reports |131|---|---|---|132| `interfaces` | Route definitions (FastAPI/Express/Spring/Django/Rails/Gin), CLI entry points (argparse, click, commander, clap), library `__all__` / public exports, GraphQL SDL, gRPC `.proto`, emitted events (Kafka topics, RabbitMQ exchanges, webhook payloads) | Endpoint added/removed, method/path changed, request or response schema changed, auth requirement changed, CLI flag added/removed, emitted event renamed or payload changed |133| `config` | Reads of `os.environ` / `process.env` / `viper`, dotenv templates, config file schemas, feature flag SDK calls | Env var added/removed/renamed, default changed, required vs optional flip, feature flag added/removed |134| `integrations` | HTTP client calls to external hosts, webhook handlers, scheduled jobs (cron, APScheduler, BullMQ, Celery), message queue producers/consumers | External API endpoint changed, new outbound dependency, webhook signature changed, cron schedule changed, queue topic renamed |135| `architecture` | Module structure, package boundaries, dependency direction | New layer introduced, boundary violation now in code, component split or merged |136| `data-model` | ORM models (SQLAlchemy, Django ORM, Prisma, Drizzle, TypeORM, Sequelize, ActiveRecord, GORM, Diesel), Pydantic/Zod/dataclass, `CREATE TABLE`, migration files (Alembic, Flyway, Liquibase, Prisma migrate, knex) | Entity added/removed/renamed, field added/removed/renamed, type changed, nullable flipped, default changed, FK or relationship changed, index added/removed |137| `data-flows` | Call sites between components, queue producers/consumers, event bus subscriptions, pipeline DAGs (Airflow, Prefect, Dagster) | New flow path, removed/short-circuited path, new fan-out, ordering or transaction boundary changed |138| `state-machines` | Explicit FSM libs (xstate, transitions, statelessLib), enum-driven status fields with guarded transitions | State added/removed/renamed, transition added/removed, guard changed, terminal state changed |139| `dependencies` | Package manifests (package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, Gemfile) + lockfiles + actual imports | Dependency added/removed, version upgraded across major/minor, new optional dep, dep moved from prod to dev, unused dep, undeclared dep used |140| `concurrency` | Worker definitions, scheduler config, async runtime usage, lock primitives, idempotency keys | Worker added/removed, queue topology changed, schedule changed, locking changed, retry/backoff policy changed |141| `glossary` | Domain types, enum names, value objects, repeated terminology in models/services | Term renamed, term removed from code, new term used in code but absent from glossary |142| `auth` | Auth middleware, JWT/session config, RBAC tables, permission decorators, secret loaders | New role/permission, removed role, scope change, secret source changed, MFA path added/removed |143| `errors` | Exception classes, error code enums, retry decorators, circuit-breaker config, idempotency keys | Error code added/removed/renumbered, retry policy changed, new circuit breaker, idempotency boundary changed |144| `observability` | Logger calls with structured fields, metrics registrations (Prometheus/StatsD/OTel), tracer spans, alert rules | Metric added/removed/renamed, log field renamed, span name changed, alert added/removed |145| `deployment` | Dockerfile, compose, k8s manifests, Helm charts, Terraform, CI workflows | Image base changed, exposed port changed, env injection changed, healthcheck changed, new pipeline stage, runner changed |146| `testing` | Test directory structure, coverage config, fixtures, mocks | New test layer, removed suite, coverage thresholds changed, fixture/mock signature changed |147| `build-release` | Version files, changelog generators, release scripts | Version scheme changed, release pipeline changed, hot-fix branch convention changed |148| `migrations` | Migration history, deprecated APIs still referenced, `@deprecated` markers | New breaking change not in migration guide, deprecated API removed, upgrade step now obsolete |149| `performance` | Benchmark scripts, load test configs, code-level perf budgets, SLO config | SLO changed, benchmark removed, perf budget added/changed |150| `compliance` | Annotated PII fields, audit log calls, retention config, encryption usage | New PII field undocumented, retention period changed, encryption algorithm changed |151| `component` | Single module/class under review | Public API signature changed, internal helper now public or vice versa, dependency change |152153## Output154155**Audit-only mode** produces:156- Comprehensive inventory of all documentation files157- Per-dimension drift report (added / removed / renamed / retyped items per dimension), with `**Source:** file:line` citations to the code that is the source of truth158- Categorized list of generic issues (duplicates, broken links, orphaned, structural) with severity levels159- Recommendations for improvements160- No files modified161162**Full refactoring mode** produces:163- All audit findings (generic + per-dimension)164- Detailed refactoring plan grouped by dimension, with proposed surgical Edits165- Executed changes with verification166- Summary of improvements made167- Confirmation that no content was lost168169## Quick Examples170171```bash172# Quarterly documentation maintenance173/docs-maintain174175# Quick health check without changes176/docs-maintain --audit-only177178# Focus on cleaning up duplicates179/docs-maintain --merge-duplicates180181# Manage API documentation only182/docs-maintain docs/api/183184# Check if README is current185/docs-maintain README.md186```187188## Tips for Best Results1891901. **Run audit-only first** on large projects to understand scope before refactoring1912. **Target specific folders** for large codebases to manage incrementally1923. **Review the plan** carefully before approving execution1934. **Use version control** - commit before running to easily review or revert changes1945. **Run after major refactors** to keep docs in sync with code changes1956. **Schedule regularly** - quarterly audits prevent documentation debt196197## Related Commands198199- `/docs-create` - Create NEW documentation from code analysis (use when docs don't exist)200- `/docs-maintain` - Audit and improve EXISTING documentation (use when docs exist but need maintenance)201- `/humanize-docs` - Rewrite existing docs to be more human-readable
acaprino