Docs sync

Documentation Sync

I'll detect what changed in the codebase and surgically update every affected documentation file — README, CHANGELOG, API docs, architecture docs, and any files under docs/ or documentation/ — so docs never drift from code.

Token Optimization

Expected range: 800–2,500 tokens (initial), 100–200 tokens (no-op when docs are already current)

Patterns used: Grep-before-Read, git diff scope, early exit, progressive disclosure

Early exit: If no code files changed since the last doc update, report "docs are current" and stop immediately.

Step 1 — Detect Changed Files

# Use staged changes if available, otherwise last commit, otherwise working tree
if ! git diff --cached --quiet; then
    CHANGED=$(git diff --cached --name-only)
    SCOPE="staged changes"
elif [[ -n "$ARGUMENTS" ]]; then
    # Support: /docs-sync HEAD~3..HEAD or /docs-sync <commit>
    CHANGED=$(git diff --name-only $ARGUMENTS)
    SCOPE="$ARGUMENTS"
else
    CHANGED=$(git diff HEAD~1 --name-only 2>/dev/null || git diff --name-only)
    SCOPE="last commit"
fi

echo "Scope: $SCOPE"
echo "$CHANGED"

If no files changed, report "Nothing to sync" and stop.

Step 2 — Discover Documentation Files

Scan the repo for doc files without reading them:

# Find all markdown/rst/txt documentation files
find . -type f \( -name "*.md" -o -name "*.rst" -o -name "*.txt" \) \
  -not -path "*/node_modules/*" \
  -not -path "*/.git/*" \
  -not -path "*/vendor/*" \
  | sort

# Identify the main docs: README, CHANGELOG, API docs, architecture docs
ls README* CHANGELOG* CONTRIBUTING* LICENSE* 2>/dev/null
# AI assistant context files — common in modern repos
ls CLAUDE.md AGENTS.md GEMINI.md COPILOT.md .cursorrules 2>/dev/null
ls docs/ documentation/ 2>/dev/null

Step 3 — Map Changed Code to Affected Docs

For each changed code file, find which doc files reference it by name, module, or path:

for file in $CHANGED; do
    # Extract meaningful name tokens (filename without extension, parent directory)
    name=$(basename "$file" | sed 's/\.[^.]*$//')
    dir=$(dirname "$file" | xargs basename)

    # Search for references in doc files
    grep -rl "$name\|$dir" \
      $(find . -name "*.md" -not -path "*/.git/*" -not -path "*/node_modules/*") \
      2>/dev/null
done | sort -u

General mapping rules (adapt to what you find in the repo):

Type of change	Likely affected docs
New public function / class / module	README usage section, API reference, relevant docs/ page
Renamed / removed symbol	Any doc that mentions the old name
New CLI flag or config option	README, config reference docs, CLAUDE.md if it describes tool usage
Dependency added / removed	README installation section, CONTRIBUTING setup guide
New file in a documented directory	README file listing or architecture doc
Bug fix with user-visible behavior change	CHANGELOG, README caveats
Breaking change	CHANGELOG, README migration section, CONTRIBUTING
New agent, command, or AI workflow	AGENTS.md agents/commands table, CLAUDE.md architecture section, README
New AI context rule or convention	CLAUDE.md rules table, AGENTS.md if it affects agent behavior
Project structure change	CLAUDE.md architecture section, AGENTS.md, README project layout

Step 4 — Read Only Affected Sections

Do NOT read entire doc files. Use Grep to find the exact lines that need updating:

# Find the section that mentions the changed item
grep -n "<item-name>" <doc-file> | head -20

# Find version or count references that may need updating
grep -n "v[0-9]\+\.[0-9]\+\|[0-9]\+ feature\|[0-9]\+ command" README.md

# Find installation or setup sections
grep -n "^## Install\|^## Setup\|^## Getting Started" README.md

Read only the relevant line ranges (use offset + limit).

Step 5 — Determine Required Updates

For each affected doc, identify the minimal change:

New public API (function, class, endpoint):

• Add one entry to the relevant section in README or API docs
• Add a CHANGELOG entry if the project uses one

Renamed or removed:

• Update every occurrence of the old name
• Add a deprecation/migration note if the project has a migration guide

New CLI flag or config key:

• Add one row to the relevant options table
• Update any example commands that show related flags

Dependency change:

• Update installation commands in README if the install step changed
• Update minimum version requirements if they changed

Breaking change:

• Add a CHANGELOG entry under the correct version heading
• Add a migration note in README or a dedicated migration doc

New agent, command, or AI skill:

• Add a row to the agents/commands table in AGENTS.md (if present)
• Update CLAUDE.md architecture section if it lists agents or commands
• Update README if it has a project infrastructure or AI tooling section

New AI context rule or project convention:

• Update CLAUDE.md rules table or the relevant rules section
• Update AGENTS.md if the rule affects how agents behave

Step 6 — Apply Surgical Updates

Use the Edit tool for each change — never rewrite an entire file. Make the smallest edit that brings the doc into sync.

# Before editing, verify the exact text to replace
grep -n "<old-text>" <doc-file>

Then apply each edit with the Edit tool, preserving surrounding formatting (table alignment, list indentation, heading levels).

Step 7 — Verify Consistency

After all edits, do a quick sanity check:

# Check that renamed items no longer appear under old names
grep -r "<old-name>" docs/ README.md 2>/dev/null

# Check for broken relative links
grep -oh '\[.*\]([^)#]*)' README.md docs/**/*.md 2>/dev/null \
  | sed 's/.*(\(.*\))/\1/' \
  | while read f; do
      [[ -f "$f" ]] || echo "BROKEN LINK: $f"
    done

Fix any remaining references before reporting done.

Step 8 — Report

docs-sync complete

Scope: last commit (3 files changed)

Updated:
  README.md          — added myFunction to API reference section
  docs/api.md        — added parameter description for --verbose flag
  CHANGELOG.md       — added entry under [Unreleased]

No changes needed:
  docs/architecture.md — no references to changed files
  CONTRIBUTING.md      — setup instructions unchanged

Skipped (doc-only changes, no code drift):
  docs/guides/tutorial.md

Edge Cases

• No git repo: Prompt the user to describe what changed; then scan all doc files for likely affected sections
• No existing docs: Note which doc files are missing; suggest creating them with /docs but do not create them automatically
• Ambiguous section: If multiple doc sections could apply, list them and ask the user to confirm before editing
• Large diffs (50+ files): Summarize by change category; ask the user to confirm scope before editing
• Generated docs (e.g., from JSDoc, Sphinx, rustdoc): Note that they need to be regenerated rather than hand-edited; skip them and report
• CHANGELOG format varies: Detect the format (Keep a Changelog, simple bullet list, etc.) from existing entries before adding new ones