📝 Skill: sync-docs-after-edit

Purpose

Keep documentation honest after local edits or commits. Distinct from sync-docs-after-git-pull (which fires after receiving remote changes) — this skill reacts to what you just changed locally.

Trigger phrases

• "sync docs"
• "check if docs are up to date"
• "update docs after my changes"
• "did my change break any docs?"
• "sync-docs-after-edit"

Steps

1. Identify what changed

# Uncommitted changes
git diff --name-only

# Last commit
git diff --name-only HEAD~1..HEAD

# Staged but not committed
git diff --cached --name-only

Collect the full set of changed source files. Exclude .md files themselves from the "changed source" list — they are the targets, not the triggers.

2. Discover all documentation files

# Find all markdown files, excluding node_modules, .git, vendor, etc.
find . -name "*.md" \
  -not -path "*/.git/*" \
  -not -path "*/node_modules/*" \
  -not -path "*/vendor/*" \
  -not -path "*/.venv/*"

3. For each .md file, assess relevance

Read the .md file and the changed source files. Assess:

4. Report per-file verdicts

Always include README.md and CHANGELOG.md as explicit rows — even if they appear unaffected. These are the two docs most likely to drift silently.

Documentation sync report
Changed source files: <list>

| Doc file | Verdict | Notes |
|----------|---------|-------|
| README.md | Needs update | Quick Start references `DB_URL` — now `DATABASE_URL` |
| CHANGELOG.md | Needs entry | No entry yet for changes in this diff |
| docs/api.md | Needs update | References `getUser()` which was renamed to `fetchUser()` |
| docs/setup.md | Up to date | |

5. Apply updates (if instructed)

If the user says "update them" or "fix the docs":

• For each file marked Needs update: make the minimal edit to bring it in line with the code changes.
• Do not rewrite docs wholesale — only fix what's factually stale.
• After editing, re-run the assessment for the updated files to confirm they're now clean.

6. Final confirmation

After all updates:

All docs synced.
Updated: <list of files changed>
No-change: <list confirmed up to date>

Output

A per-file verdict table, plus optional edits if the user confirms.

Notes

• If CHANGELOG.md exists, always flag it as a candidate — new changes often warrant a changelog entry.
• If README.md has a "Quick start" or "API" section, always read it against the changed source.
• Do not update CHANGELOG.md automatically — propose the entry and let the user confirm.