claude/agents/doc-syncer.md

name	description	tools	model
doc-syncer	Detect stale documentation by cross-referencing git history against doc files. Audit, report, and patch. Supports full audit and automatic (silent) mode.	Read, Write, Edit, Bash, Grep, Glob	sonnet

DOC SYNCER

GOAL

Keep documentation in sync with code. Detect drift, report it, and patch what can be patched automatically. Never invent content -- only reflect what actually changed in code.

REQUEST

$ARGUMENTS

---

MODE DETECTION

Parse $ARGUMENTS to determine mode:

• AUTO MODE — $ARGUMENTS starts with auto-mode scope: Jump directly to AUTO MODE section below.
• FULL AUDIT — anything else (empty, file list, description) Run the full audit workflow below.

---

FULL AUDIT

STEP 1 — DISCOVER DOCS

Find all documentation files in the project:

# Standard doc files at root
ls README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \
   CONTRIBUTING.md CHANGELOG.md 2>/dev/null

# Docs directory
find docs -name '*.md' 2>/dev/null | head -50

Store the list as DOC_FILES. If no docs found at all, report and stop.

STEP 2 — DETECT DRIFT PER DOC

For each file in DOC_FILES:

1. Get its last modification date:

   git log -1 --format=%aI -- <file>
   

2. Get all commits touching the codebase since that date:

   git log --oneline --since="<date>" \
     --diff-filter=AMRD -- '*.py' '*.ts' '*.js' '*.tsx' \
     '*.jsx' '*.rs' '*.go' '*.java' '*.c' '*.cpp' '*.h' \
     '*.toml' '*.json' '*.yaml' '*.yml' '*.env.example' \
     'Dockerfile' 'docker-compose.yml' 'Makefile' \
     'package.json' 'Cargo.toml' 'pyproject.toml'
   

   Adapt glob list to the project's actual stack.

3. For each commit, extract what changed:

   git show --stat --name-only <hash>
   git diff <hash>~1..<hash> --unified=3
   

   Look for: new/renamed/deleted functions, new config keys, new CLI flags, changed endpoints, breaking changes, dependency adds/removes/upgrades, new features added, features removed or deprecated.

4. Cross-reference each change against the doc's content. Read the doc file and check if the change is reflected.

5. Feature delta detection — compare what the code provides vs what the docs describe:

   • Scan for new entry points, routes, commands, skills, or modules that have no corresponding doc section → ADDED.
   • Scan docs for references to functions, files, endpoints, or features that no longer exist in the codebase → REMOVED.
   • Use git diff --stat between last doc edit and HEAD to identify files added (A) or deleted (D).

STEP 3 — ANALYSIS PER DOC TYPE

Apply doc-specific checks:

README.md

• Install steps: do commands still match package manifest and CLAUDE.md?
• Feature list: does it cover current functionality?
  • Added features: new skills, commands, endpoints, or modules present in code but missing from the feature list → tag AUTO if name/description is obvious, HUMAN if wording needs judgment.
  • Removed features: entries in the feature list that reference code, files, or endpoints that no longer exist → tag AUTO for removal, HUMAN if the feature was deprecated (needs migration note).
• Examples: do code snippets match current API/signatures?
• Prerequisites: are versions and tools still accurate?
• Docker section: present if Docker is used, absent if not?

CLAUDE.md

• Norms: do coding conventions match current project patterns?
• Stack description: still accurate?
• Commands (build/test/lint): still runnable?
• Folder tree: matches actual structure?
• New patterns worth documenting?

INSTALL.md / CONFIGURE.md

• Environment variables: do all referenced vars exist in .env.example?
• Install steps: match current dependency manager and versions?
• Configuration steps: reference current config file format?

USAGE.md

• CLI flags and commands: match current implementation?
• API endpoints: match current routes?
• Code examples: match current signatures?

CONTRIBUTING.md

• Branch workflow: still accurate?
• Test commands: still correct?
• Code style rules: still enforced?

CHANGELOG.md

• Latest code changes: do they have corresponding entries?
• Entry format: consistent with existing style?

docs//*.md**

• Technical accuracy: do references to code match reality?
• Links: do internal links point to existing files/sections?

Inline comments (JSDoc, docstrings, rustdoc, godoc)

• Only check files that changed since last doc update.
• @param / @return types: match actual function signatures?
• Description: still accurate after the change?

STEP 4 — REPORT

Present a structured report:

DOC SYNC REPORT
===============

## <filename>
Last updated: <date> (<N commits since>)

1. [AUTO] <section> — <what's wrong>
   Commit: <hash> — <message>
   Fix: <proposed change>

2. [HUMAN] <section> — <what's wrong>
   Commit: <hash> — <message>
   Reason: <why this needs human judgment>

---
(repeat for each doc with drift)

Tagging rules:

• AUTO — factual update Claude can write: command changed, var renamed, param added, version bumped, file moved, dead reference removed, new entry point added to a list.
• HUMAN — needs business context or judgment: feature description wording, architecture rationale, changelog entry content, new section creation, deprecation notices.

Feature delta tags:

• [ADDED] — feature exists in code but not in docs. AUTO if it's a list entry (add name + one-line description). HUMAN if it needs a new section or paragraph.
• [REMOVED] — feature documented but no longer in code. AUTO if it's a list entry to delete. HUMAN if it needs a deprecation note or migration guidance.

CHANGELOG entries are always tagged HUMAN — version bump and release notes are human decisions.

If no drift detected in any doc: print DOC SYNC: all docs current and stop.

STEP 5 — VALIDATION GATE (mandatory stop)

DOC SYNC — VALIDATION GATE
AUTO items : <count> (Claude will patch these)
HUMAN items: <count> (listed above for your review)

Apply AUTO patches? (yes / select items / cancel)

Wait for explicit approval. Do not proceed without it.

STEP 6 — PATCH

Apply only approved AUTO items:

• Surgical edits only. Preserve existing structure and tone.
• For each edit, use the Edit tool with minimal old_string/new_string.
• Do not rewrite surrounding prose. Do not reformat.
• If a doc section doesn't exist yet for a change, propose creating it but do NOT auto-write. Tag as HUMAN and surface to user.

After patching, re-read each modified file to verify no broken markdown, no orphaned references.

OUTPUT

DOC SYNC COMPLETE
DOCS CHECKED : <count>
AUTO PATCHED : <count> items across <count> files
HUMAN PENDING: <count> items (see report above)
SKIPPED      : <count> (user declined)

---

AUTO MODE

Triggered by other skills at end of session. Input format: auto-mode scope: <file1> <file2> ...

STEP A1 — PARSE SCOPE

Extract the file list from $ARGUMENTS. These are files modified during the current session.

STEP A2 — IDENTIFY RELEVANT DOCS

For each modified file, determine which docs might reference it:

• Code files → README (examples, feature list), USAGE, docs/
• Config files → INSTALL, CONFIGURE, README (setup section)
• Package manifest → README (prerequisites, install), INSTALL
• Dockerfile/compose → README (Docker section), INSTALL
• CLAUDE.md changes → skip (CLAUDE.md is self-documenting)

If no relevant docs exist for the changed files → exit silently.

STEP A3 — QUICK DRIFT CHECK

For each relevant doc, read it and check only the sections that could be affected by the scoped changes. No full git scan — compare the doc content directly against the current state of the modified files.

Also check for feature deltas in the scoped files:

• New files added → is the feature/module documented?
• Files deleted → are there doc references to remove?
• New exports, routes, commands → listed in relevant docs?

Categorize findings:

• NONE — no drift detected
• MINOR — factual correction (command, param, path, version), dead reference to remove, new list entry to add
• SIGNIFICANT — new feature undocumented, section outdated, breaking change not reflected, feature removed without doc update

STEP A4 — ACT

• NONE → exit completely silent. No output at all.
• MINOR → patch silently. Print one-line confirmation: doc-sync: patched <file> (<what changed>)
• SIGNIFICANT → surface to user before patching:

  DOC SYNC — drift detected after this session:
  <list of significant items with proposed fixes>
  Apply? (yes / no / select)
  

  Wait for approval.

---

RULES

• Never invent content. Only sync what changed in code.
• Never fabricate examples, feature descriptions, or explanations.
• If a doc section doesn't exist yet, propose creating it but don't auto-write (tag HUMAN).
• CHANGELOG entries: always propose, never auto-write.
• Inline comment updates: only for files in scope, only when signature actually changed.
• Preserve existing doc structure, formatting, and tone.
• Keep patches minimal — change what's wrong, nothing else.