# Docs

> Generate, review, and update engineering documentation in simple technical English. `new` scaffolds the doc skeleton via a script (@agent prompts, no prose); `retcon` authors real content from the codebase. Review produces a replacement report; update consumes it. Triggers on: "docs new", "docs update", "docs review", "docs retcon", "create docs", "generate docs for", "update docs", "review docs", "document this", "add docs".

- Skill: `cloudvoyant/docs` (Agent Skill, multi-file: 40 files)
- Install (CLI): `npx skillmds@latest add cloudvoyant/docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cloudvoyant/docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: cloudvoyant (https://skillmd.com/u/cloudvoyant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cloudvoyant/docs

---


# docs

Generate, update, review, and retroactively create engineering documentation for any project.

Triggers: "docs new", "docs update", "docs review", "docs retcon", "create docs", "generate docs for", "update docs", "review docs", "document this", "add docs"

## Critical Rules

- **Never execute workflow logic here** — this file only parses args and dispatches
- **Step 0 always runs first** — no exceptions
- **Empty verb → ask the user what they want** (AskUserQuestion, numbered-list fallback on non-Claude-Code platforms) — never run help silently. **Unknown verb → run `help.md`** — never error silently.
- **Markdown output: soft-wrap prose, never hard-wrap** — when any docs workflow writes a `.md` artifact, write each paragraph as one continuous line; do not insert manual newlines to wrap prose at a fixed column width. Newlines still separate paragraphs, list items, headings, and code fences. (Full guidance: `references/language-guide.md`.)

## Skill directory resolution

Workflows invoke the vendored scripts (`scripts/scaffold.py`, `scripts/scope.py`) via `$SKILL/scripts/...`. Resolve the skill package root once and export it so every workflow bash block uses the same path — this works both from the repo `skills/docs/` checkout and from an installed copy. Do NOT rely on `$0` (it is the invoking shell, not this file):

```bash
if [ -n "${BASH_SOURCE:-}" ]; then
  SKILL=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
else
  SKILL="${SKILL:-$HOME/.claude/skills/docs}"
fi
export SKILL
```

## Docs directory resolution

The docs directory is `docs/` by default. Override it per project with a `"docs_dir"` field in the codevoyant store's `.codevoyant/metadata.json` (a repo-root-relative path). Resolve once and export so every workflow uses the same path:

```bash
resolve_docs_dir() {
  local root cfg d
  root="$(git rev-parse --show-toplevel 2>/dev/null)" || root="$PWD"
  cfg="$root/.codevoyant/metadata.json"
  d=""
  if [ -f "$cfg" ]; then
    d="$(python3 - "$cfg" <<'PY' 2>/dev/null
import json, sys
try:
    print(json.load(open(sys.argv[1])).get("docs_dir", ""))
except Exception:
    pass
PY
)"
  fi
  DOCS_DIR="${d:-docs}"
}
resolve_docs_dir
export DOCS_DIR
```

`$DOCS_DIR` is the single source for where docs live; every workflow that writes or reads docs uses it instead of the literal `docs/`.

## Step 0: Parse Arguments

The raw invocation args (filled by Claude Code / OpenCode slash commands): `$ARGUMENTS`. If this line is not filled in, read the verb and remaining args from the user's current message.

Read the invocation from the current request. VERB = first non-flag argument; REMAINING_ARGS = everything after VERB, preserving order and flags. The invocation may arrive inline (Claude Code or OpenCode slash path) or as a plain message (skill-tool loading, other agents). If VERB is empty (nothing parseable was typed), ASK the user what they want (AskUserQuestion: new / update / review / retcon / validate / help; numbered-list fallback on non-Claude-Code platforms) instead of silently running help. If the user explicitly typed `help` or an unrecognized verb, run help. Full contract: `skills/shared/arg-handling.md`.

```bash
VERB="[first non-flag argument, or empty]"
REMAINING_ARGS="[everything after VERB, preserving order and flags]"

case "$VERB" in
  "")              ask the user what they want ;;   # empty invocation → ask, never silent help
  "generate")      VERB="new" ;;
  "create")        VERB="new" ;;
  "add")           VERB="new" ;;
  "architecture")  VERB="new"; REMAINING_ARGS="architecture $REMAINING_ARGS" ;;   # /docs architecture → /docs new (architecture)
  "readme")        VERB="new"; REMAINING_ARGS="readme $REMAINING_ARGS" ;;         # /docs readme → /docs new (readme)
  "user-guide")    VERB="new"; REMAINING_ARGS="user-guide $REMAINING_ARGS" ;;     # /docs user-guide → /docs new (user-guide)
  "development-guide") VERB="new"; REMAINING_ARGS="development-guide $REMAINING_ARGS" ;;  # /docs development-guide → /docs new (development-guide)
  "ci")            VERB="new"; REMAINING_ARGS="ci $REMAINING_ARGS" ;;             # /docs ci → /docs new (ci); ci.md covers CI/CD + infrastructure
  "audit")         VERB="review" ;;
  "check")         VERB="review" ;;
  "validate")      VERB="validate" ;;
  "backfill")      VERB="retcon" ;;
  "retrofit")      VERB="retcon" ;;
esac
```

## Step 1: Dispatch to Workflow

Read and execute `references/workflows/{VERB}.md`, passing `$REMAINING_ARGS`.

If `references/workflows/{VERB}.md` does not exist, fall back to `references/workflows/help.md`.

## Workflow Index

- **new** (`references/workflows/new.md`) -- initialize the docs SKELETON: scan the repo and run `scripts/scaffold.py` to copy template skeletons with `@agent` prompts (no prose, no code analysis). Bare `/docs new` scaffolds the base structure (README + `docs/{user-guide,ci,development-guide,architecture/index}`, monorepo per-app/lib component docs); named targets scaffold a single skeleton
- **update** (`references/workflows/update.md`) -- update an existing doc: consumes review report if present, otherwise audits and applies minimal fixes, escalates to review-first when changes are too large; `--scaffold` creates missing files/sections with template headings only
- **review** (`references/workflows/review.md`) -- audit docs for template/language compliance and write a replacement report to `.codevoyant/review/{slug}/docs-review.md` (read-only)
- **retcon** (`references/workflows/retcon.md`) -- intelligent backward authoring: the ONLY command that writes real content — moves existing docs to `docs/legacy/` (carrying their facts forward), analyzes the codebase, and fills the full mandated doc structure with accurate prose, diagrams, and tables; ends by validating every doc's `globs` against the real code tree
- **validate** (`references/workflows/validate.md`) -- code-reading check: confirms each doc's `globs` are valid (point at real paths) and comprehensive (every discovered component has an owning doc), and that docs obey glob/component boundaries
- **help** (`references/workflows/help.md`) -- print command reference