docs-update

Update Documentation

Synchronize documentation with the current codebase state: one file, a category, or everything in docs/.

Anti-Hallucination Guidelines

Every statement written must trace back to a file read or grepped this run:

1. Verify each claim before writing it, read the actual source, don't recall it
2. Get counts from find/grep, never estimate ("5 services" means 5 files were counted this run)
3. Delete claims about features that no longer exist rather than leaving them stale
4. After writing, re-read the diff and drop anything not backed by evidence gathered this run

Workflow

Phase 1: Resolve Scope

Parse the invocation argument:

• No argument or all: update every doc that exists in docs/
• <doc-name> (e.g. architecture): resolve via the mapping below, update only that file
• category:<name> (core, data, infrastructure, development): update every doc in that category

Existence check: stop before doing anything else if the target is missing. This skill only updates docs that already exist; it never creates one.

• all or category:<name>: silently exclude any mapped path that isn't on disk (e.g. find docs/*.md and intersect with the category's paths); the run proceeds with whatever remains
• <doc-name>: resolve the path, then check it with test -f <resolved-doc-path> (or Read). If it does not exist, STOP the entire skill run right here: do not read further, do not run Phase 2-5, do not Write or Edit that path under any pretext (not as a "special case," not with a caveat about verified content). Tell the user the doc doesn't exist yet and point them to docs-init, which owns creation and the canonical templates. This is the final action for that run.

For a multi-doc run that passes the existence check, track progress with TodoWrite: one todo per document, marked in_progress while it's being worked and completed once written.

Phase 2: Check Freshness

For each doc resolved in Phase 1 (using its actual path, not a fixed one), compare its last commit against source changes since:

git log --since="$(git log -1 --format=%ai -- <resolved-doc-path> 2>/dev/null || echo '30 days ago')" --oneline --name-only -- . ':!docs' | head -30

A doc whose last update predates relevant source changes is a candidate for this run. If git history is unavailable (no .git, doc untracked, first commit), fall back to the commands in references/change-detection.md and note in the final report that freshness couldn't be determined from git.

Phase 3: Verify Against the Codebase

Single document: read it fully, then grep the codebase for each claim it makes (component names, counts, file paths, tech stack). No subagent needed, one Explore pass funnels into one file write either way.

Multiple documents (all or category mode): spawn one subagent per document so verification runs concurrently, see references/update-strategies.md for the per-document-type checklist and prompt pattern. If no Task/subagent tool is available, run the same read-verify-write pass for each document sequentially instead.

Phase 4: Write Updates

• Preserve manually added sections and any content that doesn't match the template structure: only touch parts backed by verified facts from Phase 3
• Templates are shared with docs-init: ../docs-init/assets/templates/ relative to this skill's own directory (works when both skills are installed side by side, e.g. via the cc-arsenal plugin or npx skills add). If docs-init isn't installed alongside this skill, fetch the same templates from the cc-arsenal repo instead of inventing structure
• Before filling placeholders, run grep -oE '\{\{[A-Z_]+\}\}' <template-file> to see the tokens that specific template actually uses: each template has its own set (architecture.md alone uses over a dozen), never assume a fixed list
• Regenerate diagrams whose depicted components/entities changed
• Remove claims Phase 3 could not verify
• If it's ambiguous whether a section is custom or auto-generated, ask before overwriting rather than guessing

Phase 5: Report

List documents updated (with what changed and numbers pulled from Phase 3, e.g. "3 services found" not "several services"), skipped (already fresh), and not found (excluded from an all/category run because the file doesn't exist, mention docs-init, don't create it). This skill never reports a "created" doc; creation is docs-init's job.

Example Output: All Docs Update

Documentation Update Complete

Updated (2 docs):
  docs/architecture.md (added AuthService, NotificationService — found via grep of src/services/)
  docs/data-model.md (schema changed, ER diagram regenerated from 6 models)

Up to Date (1 doc):
  docs/onboarding.md (no source changes since last update)

Skipped — could not verify (1 doc):
  docs/security.md (claims about SSO could not be confirmed in code, left as-is, flagged for manual review)

Example Output: Specific Doc Update

Architecture Documentation Updated

File: docs/architecture.md

Changes:
  Added 2 new services (AuthService, NotificationService) — src/services/auth.py, src/services/notify.py
  Updated architecture diagram to include the new message queue integration
  Preserved custom "Deployment Notes" section (not touched)

Verified:
  5 services total (find src/services -name '*.py' | wc -l)
  3 databases: PostgreSQL, Redis, MongoDB (grep of config/database.yml)

Example Output: Target Doc Doesn't Exist

docs/security.md doesn't exist yet — nothing to update.

This skill only refreshes existing docs. Run docs-init to create
docs/security.md from the canonical template first, then re-run
docs-update security to keep it in sync going forward.

No file was written and no other phase ran.

Notes

• Never creates a doc that doesn't exist: a missing target stops the run and points to docs-init instead
• Preserves custom content by default: asks rather than overwrites when a section's status is unclear
• Git-aware: freshness comes from git log, not assumption
• Safe to run repeatedly (after refactors, schema changes, infra changes, or before onboarding/releases)
• For a full category, see references/update-strategies.md for the category-level output format and per-doc-type verification steps

Additional Resources

• references/update-strategies.md: parallel subagent pattern, per-document-type checklist, category-update output format
• references/change-detection.md: fallback change-detection commands when git history is unavailable