Skills / Project hygiene

docs-sync

Checks a repository's docs against its code and the project docs standard: proposes missing pieces, a refreshed docs/CURRENT-STATE.md, the drift it found and "Likely agent mistakes" from git history, and writes nothing until you approve.

Group

Project hygiene

Kind

Action

Writes

Approved doc edits

Asks before

Any write: a numbered list, answered A, B or C

When it runs

When the docs may be stale, after a large change, or when setting up docs in a project:

• Likely agent mistakes here
• refresh the docs
• are the docs up to date
• sync the docs with the code

What it does

1. Applies the standard. A root AGENTS.md under 100 lines (purpose, commands, likely agent mistakes, stack, architecture, conventions, invariants, a docs map and the sync rule), a one-line CLAUDE.md that imports it, a short _Context.md signpost, DESIGN.md for a project with a UI, a git-ignored state file, status/owner/last-verified frontmatter on every doc, a docs/index.md task table, docs/CURRENT-STATE.md, docs/pitfalls.md, numbered decision records (with a status line and a "Revisit when" section) and runbooks. A decision whose reason is in neither the history nor the docs gets "Reason not recorded" and becomes an open question; it never infers a rationale from the code. It proposes only pieces that would carry real content now, and respects an existing layout that serves the same purpose.
2. Takes inventory of the instruction files and the docs root, the last 30 commits and the current short SHA.
3. Lists missing pieces, each with the content it would start with.
4. Finds drift. Commands in the docs that are not scripts in the manifest or Makefile, CI scripts no doc mentions, paths and path:line references that no longer exist, stack versions that differ from the lockfile, a CURRENT-STATE.md commit that is not an ancestor of HEAD or is more than 50 commits behind, claims under "Works" whose entry point is gone, a stale "State as of" date, last-verified dates older than the code they cite, a DESIGN.md older than the styling sources, and decision records that contradict each other or the code, reported before any broad change. Each finding names the doc's path:line, the claim and the contradicting evidence; probes that did not apply are named too.
5. Drafts a new CURRENT-STATE as a diff: every line checked against the code, shipped work added from the commits since, Verified at commit: set to HEAD.
6. Proposes likely agent mistakes. At most three, from reverts and repeated fix commits in git history and from your corrections in the current conversation, each with its evidence as a commit or session date. Without evidence it proposes nothing.
7. Reports and asks. One numbered list with A (all, recommended), B (a list of numbers) or C (none). After approval it applies exactly those items and shows git diff --stat.

Example output

Docs sync — <repo> at <short sha>
Missing: 3   Drift: 5   CURRENT-STATE: 41 commits behind   Mistake candidates: 2

1. [missing] docs/pitfalls.md — two entries: the disabled lint rule in eslint.config.js:12, the retry cap
2. [drift] AGENTS.md:24 says `npm run test:e2e`; package.json has no such script
...
Apply which? A: all (recommended)  B: list numbers  C: none

Boundaries

Related

• instruction-review trims and extends CLAUDE.md or AGENTS.md.
• project-baseline checks the engineering practices around the docs.
• Engineering skills in the functional specification.