Docs

Docs

Keep ./docs/ honest. Scout the code, diff it against what the docs claim, write what's true. Small canonical set - easy to keep current, hard to let rot.

What this skill is - and isn't

./docs/ is team-facing truth. Journals are personal. Plans/reports live under ./plans/. Changelog, roadmap, and PR-style narrative are intentionally not in this skill's scope - those rot fastest and vd:ship / vd:journal already cover them.

Two surfaces, one skill: init/update/check/adr own internal Markdown; site owns the rendered public website (formerly the separate tech-docs skill). Internal-content hard rules 1-5 below apply to the Markdown surface; the site surface carries its own rules in references/site-workflow.md. Rules 6-7 (unslop + prose standard) apply to both.

Subcommands

Parse $ARGUMENTS first word (in runtimes without $ARGUMENTS substitution, use the text following the skill name in the user's message):

• init / update / check / adr → load the matching reference
• site → load references/site-workflow.md
• empty / unclear → AskUserQuestion with the options (AskUserQuestion in Claude Code; plain-text question elsewhere). Don't auto-run init - it writes files.

Flags

Canonical doc set

Intentionally short. Every file here earns its place - code-derivable, frequently consulted, and stable enough not to need weekly rewriting.

Out of scope (by design):

• Changelog → vd:ship writes CHANGELOG.md directly
• Project roadmap → lives in plans (./plans/) or your issue tracker, not here
• Codebase summary → vd:scout produces this on demand; doesn't need a static file
• PRD / requirements → product artifact, not a code-derivable doc

If a project has good reasons to maintain those, add them outside vd:docs's automated touch - this skill won't read, write, or validate them.

docs/decisions/ (ADRs) is a special case - append-only decision history written by the adr subcommand, not current-state docs. It is exempt from freshness, size-budget, and citation validation: an old ADR is correct (it records what was decided then), and a superseded one stays in place with its status flipped. check must skip docs/decisions/.

Pre-flight: missing ./docs/

Before any subcommand except init and site (site runs its own inspection in references/site-workflow.md and asks where the rendered site should live):

1. If ./docs/ does not exist → ask the user: run init now, or abort?
2. If ./docs/ exists but is empty → same question.
3. If a single required file is missing → flag it in the plan; create it as part of the run.

Never create ./docs/ silently. The user owns this directory.

Writer strategy

When delegating, pass: scout digest, current doc LOC table, the user's $ARGUMENTS, plan dir (if any). Do not pass full file contents - let the subagent re-read what it needs.

After init or update writes files, list every changed doc with an openable location: [deployment.md](/absolute/path/to/docs/deployment.md) and, when helpful, file:///absolute/path/to/docs/deployment.md. Repo-relative paths are fine as secondary context, but never hand off only a basename.

Token efficiency

• Scout in parallel, write once. Don't re-scout per doc file.
• Read docs in bulk when many. If ls docs/*.md | wc -l ≥ 4, spawn Explore subagents to read in parallel (read sequentially if subagents unavailable) - see references/update-workflow.md Phase 1.5.
• Don't dump full git diff into the subagent prompt - git log --oneline + git diff --stat is enough; the subagent pulls scoped diffs only for files it names.
• --dry-run costs almost nothing - run it first on unfamiliar repos.

Quality bar

• Every claim has a citation. Architecture docs name the file path. Tech-stack entries name the version (from lockfile / package.json / go.mod). No "the system uses XYZ" without src/...:N.
• No filler. If a section in a template has nothing concrete, delete it - don't pad with "TBD".
• Size budget. docs.maxLoc from session context (default 800). Over budget → split or trim, not "accept as-is".
• Validation runs after every write. references/update-workflow.md Phase 4 - non-blocking, but report what it finds.

Workflow position

Typically follows: vd:ship (after the PR lands, sync ./docs/ to the new reality), vd:cook (end of plan), major refactor or migration.

Typically precedes: Nothing - vd:docs is terminal. Next pipeline starts at vd:scout or vd:plan.

Do not run vd:docs mid-implementation - docs drift faster than code does. Wait until the code is stable.

Hard rules

1. Never write outside ./docs/ or ./README.md, unless the user explicitly names a project guidance file such as AGENTS.md or CLAUDE.md. Plans, journals, and reports have their own homes.
2. Never invent. If the scout digest doesn't support a claim, the docs don't make it.
3. Never run init on a populated ./docs/. update is the right verb - init is for empty trees.
4. --dry-run before any big sync. Especially on repos you don't own well.
5. One file write per doc. No append-mode, no patch-on-patch. Subagent rewrites the file in full or not at all.
6. Unslop every doc. Final pass with vd:unslop before the file is written - no AI tells, no em dashes, no puffery.
7. Structure and style follow the prose standard. Route each page by Diataxis (tutorial / how-to / reference / explanation) and apply the sentence rules in references/technical-writing.md. That file owns structure and style; vd:unslop owns the de-AI final pass.