readme-sync

name	readme-sync
description	Use when the user asks to "update README", "sync README", "check README", "is README up to date", "are docs consistent", "does README match the code", or any request to verify or update README.md to match the current state of the codebase.

README sync

Audit README.md for consistency with the actual codebase and suggest (or apply) updates.

Arguments (from the user's request)

• --check — only report issues, don't apply fixes (default)
• --fix — apply fixes to README.md
• --since <commit> — only check changes since a specific commit

1. Gather context

• README present: ls README.md 2>/dev/null
• Recent commits: git log --oneline -10
• Project type: ls pyproject.toml Cargo.toml package.json 2>/dev/null
• Task runner: ls justfile Makefile 2>/dev/null

2. Read current state

Read the full README.md; read recent git log to understand what changed (git log --oneline -20). If --since is specified, scope to git diff <commit>..HEAD --name-only.

3. Check categories

Install instructions — package name matches manifest; install commands work (pip install, uv add, npm install); dependency requirements match.

CLI commands & usage examples — documented commands exist in project scripts; flags/options match the implementation; run documented non-destructive examples to verify.

API/code examples — imported names exist in the package's public API (__init__.py, __all__); documented signatures match reality; example code would run.

Project structure — documented directories/files exist; flag removed/renamed files.

Links & references — internal links (to other .md files) are valid; referenced paths exist.

Task runner recipes — referenced just/make commands exist; flag important new recipes that aren't documented.

4. Report

## README Sync Report

### Inconsistencies Found
1. **<category>**: <description>
   - README says: `<quoted text>`
   - Actual: `<what's true now>`
   - Fix: <suggested change>

### Missing Documentation
- <new feature/command not mentioned in README>

### Outdated Sections
- <section referencing removed/changed functionality>

### README is Current
- ✅ <section that is accurate>

5. Apply fixes (if --fix)

Apply the suggested changes to README.md.

Important notes

• Only suggest changes for real inconsistencies — don't rewrite style or add sections unprompted.
• If the README is correct and up to date, say so explicitly.
• Focus on factual accuracy (commands, paths, names) over prose quality.