---
name: doc-sync
description: Reconcile docs with code after a change (or as a periodic audit). Use before calling any change "done", at the end of every PR, or when asked to audit doc/code drift. Enforces this repo's hard rule: code change = doc change in the same commit.
---

# doc-sync — keep docs and code converged

This repo treats doc lag as **an unfinished bug** (see AGENTS.md § Doc-sync discipline).
This skill is the executable procedure; the canonical *mapping table* (which change owes
which doc) lives in **AGENTS.md** — read it there, do not copy it here.

> This file is canonical at `.agents/skills/doc-sync/SKILL.md` (`.claude/skills/doc-sync`
> is a symlink). The skill itself iterates: when a run shows an instruction here is wrong
> or misleading, fix it **in the same pass**, with the run's evidence in the commit message.

## Mode 1 — per-change sync (run at the end of every change)

1. **Determine the change surface.**
   `git diff --stat origin/main...HEAD` (or the staged diff for uncommitted work).

2. **Map each changed path against the AGENTS.md doc-sync table.** Produce the list of
   docs owed by this change. The high-traffic rows:
   - `src/db/schema.ts` → `docs/generated/db-schema.md` (hand-maintained snapshot — **no
     generator script exists despite the `generated/` dir name**; update the table row
     *and* any enum lists by hand; prod DB migrates via `prod:up` → `db:push:prod`).
   - Routes / CLI subcommands / daemon protocol → `ARCHITECTURE.md` §II codemap + §IV contracts.
   - Module purpose / boundary / invariant changed → `ARCHITECTURE.md` §II–IV.
   - Feature completed or modified → `FEATURES.md` checkbox (**checkbox + a short note**;
     long verification narratives belong in the PR, not the checklist).
   - TODO / known drift left behind → `docs/tech-debt-tracker.md` new entry
     (next free ID — check the **archive** too so IDs are never reused).
   - `src/daemon/**` shipped in the bundle → bump `packages/daemon/package.json`,
     cut a GitHub Release, **and add the version's `CHANGELOG.md` entry**. Merged ≠ shipped.

3. **Status single-source rule.** Security/authorization item states (F*/C*/IDOR-B*) live
   **only** in `docs/authorization.md` §6. Other docs (PLANS, tech-debt I44) may point
   there but must never mirror per-item states — mirrored lists are how C10 stayed
   "remaining" for weeks after it was fixed. Detect mechanically, don't trust prose:
   `grep -rnE '\b(C1[0-2]|C[1-9]|B[1-6]|F[0-9]|IDOR)\b' --include='*.md' docs/ *.md | grep -vE 'authorization\.md|docs/exec-plans/|docs/superpowers/'`
   (historical plan/spec records legitimately narrate the states they shipped — the rule
   polices *live* docs). A hit naming an item's *state* (open/fixed/remaining) is a
   violation; a bare pointer to authorization.md §6 is fine.

4. **Staleness check on every doc you touched.** For each edited doc: file paths it names
   exist; `tech-debt I<n>` / `D<n>` references resolve (tracker or archive); counts/enums
   match code (`grep`, `wc -l` — better: drop volatile numbers entirely, per
   ARCHITECTURE.md's header rule).

5. **Hygiene gates.**
   - No personal/machine refs in what this change **adds** (core belief #9). Grep the
     *added diff lines*, not whole files:
     `git diff origin/main -- <files> | grep '^+' | grep -E '~/\.claude|/Users/'`.
     A personal absolute path (`/Users/<name>/…`) is a violation. Two known non-violations
     that this grep still surfaces: a generic runtime path that is product behavior
     (e.g. `~/.claude/skills` as Claude CLI's global skills dir), and a tech-debt entry
     *quoting* a personal path as the evidence of the debt it records. Judge, don't
     blind-fail — but never add a *new* personal path outside those two shapes.
   - Touched `src/daemon/prompt.ts`? Grep for provider-specific tool names
     (`Read`, `cat`, `grep`, vision hints) → expect zero hits (code-quality red line).

6. **Fail loud.** In the PR/summary, list: docs updated · docs checked-and-clean ·
   drift found but deferred (with its new tech-debt entry ID).

## Mode 2 — periodic full audit (on request / doc-gardening)

Cross-check the status documents against code and each other; they drift fastest:

1. `FEATURES.md` — sample every `[ ]` unchecked line: is the feature actually still
   missing? (grep the endpoint / CLI verb / component). Unchecked-but-shipped is the
   most common rot.
2. `docs/PLANS.md` — every referenced plan file exists; Active items are still active;
   completed plans moved to `docs/exec-plans/completed/` **with their status line
   updated** (a moved plan still saying "merge pending <date>" is half-finished rot).
3. `docs/tech-debt-tracker.md` — no duplicate IDs (incl. vs the archive); ⬜/🟡 entries
   spot-checked against code; newly-✅ entries: **move the full row** to the archive.
   The tracker keeps no stub — it holds open items only; cross-references resolve by
   grepping both files.
4. `docs/authorization.md` §6 vs any doc that mentions security items — pointers only,
   no mirrored states (run the Mode 1 step-3 grep).
5. `ARCHITECTURE.md` §II — new substantive modules (>50 lines) present in the codemap.
   Recipe: `git log --since=<last audit> --name-only --diff-filter=A --pretty=format: -- 'src/*' 'web/src/*'`,
   then check each surviving non-test file's basename appears in the codemap. Named files
   exist; `CHANGELOG.md`'s newest **version** heading (the `[Unreleased]` section doesn't
   count) matches `packages/daemon/package.json`.
6. **Size / density audit — docs must stay maps, not manuals.** Line counts hide bloat
   (long table rows); rank by bytes: `git ls-files '*.md' | xargs wc -c | sort -rn | head`.
   For each fat doc, check it against **its own stated form rule** (FEATURES' "checkbox +
   short note" header, ARCHITECTURE's "write only what doesn't change often" header) —
   self-rule violations are the strongest trim mandate. Cut change-history narrative
   ("the former X was removed…", "before this fix…") and verification evidence — git log
   and PRs own those. Frozen plan/spec archives of shipped work are deletable (git
   history retains them); before deleting, grep for inbound references incl. from `src/`.
7. **`README.zh-CN.md` parity** — diff section structure + bullet counts against
   `README.md`; the zh mirror silently misses EN feature edits (drift is one-directional).
   Small deltas: translate in the same pass. A backlog: open a tech-debt entry.

Report findings with file:line evidence; fix mechanically-safe drift in the same pass,
open tech-debt entries for anything needing a decision.