docs-sync

name	docs-sync
description	Rewrites stale `README.md` and `docs/*.md` sections based on changes since main. Use before staging, or when asked to "sync docs" or "update the docs". Do NOT use for changelog updates or `CLAUDE.md`/`GEMINI.md` updates.

Docs sync

Read these files from the project root in parallel:

• .claude/standards/prose.md: prose conventions for all generated text
• .claude/standards/readme.md: README structure, required sections, and content rules

Context

Run these commands in parallel:

• git diff --cached main -- . ':(exclude)*.lock' ':(exclude)*-lock.json' 2>/dev/null || echo "NO_DIFF"
• git diff --cached --name-only main 2>/dev/null || echo "NO_FILES"
• git status --short 2>/dev/null || echo "NO_STATUS"

Guards

• If git diff --cached main output is empty and git status --short output is empty, stop: ❌ No changes since main. Nothing to sync.

Discovery

Discover docs dynamically. Do not hardcode paths:

• Glob README.md at project root
• Glob docs/**/*.md

Read each discovered file in parallel.

Analysis

For each discovered doc, classify as one of:

• stale: the diff touches something the doc describes
• unrelated: no overlap between diff and doc content

Classify at the section level, not the file level. A doc edited earlier in the session can still be partially stale. For each diff surface, verify the corresponding section is synced.

Action

Rewrite only the stale sections. Do not touch sections unrelated to the diff. Write the updated file immediately after the preview. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.

Response format

Preview

Changes since main: <n> files Docs discovered: <list>

Doc	Status	Action
README.md	stale	update
docs/api.md	unrelated	skip

After outputting the preview, write all stale updates immediately.

Summary

One line per file, using the same relative path format as the preview table (e.g. README.md, docs/api.md):

✅ Updated: <relative-path>
⏭️  Skipped: <relative-path>