Update Docs
Detect code changes since the last documentation sync and update CLAUDE.md / docs/ accordingly. This is a two-phase workflow: propose → confirm → apply. Never modify docs before the user confirms.
Step 1 — Find the baseline
Determine the last commit where docs were in sync, in this priority order:
User-specified range: if the user names a commit, tag, or PR (e.g. "diff from abc1234", "only PR #456"), use that and skip auto-detection.
Marker file: if docs/.last-sync exists, read the commit hash from it.
Fallback: last commit that touched docs/:
git log --oneline -1 -- docs/ CLAUDE.md
Step 2 — Collect changes since the baseline
git diff <baseline>..HEAD --stat -- ':!docs' ':!CLAUDE.md'
git log --oneline <baseline>..HEAD -- ':!docs' ':!CLAUDE.md'
If there are no changes, tell the user the docs are already up to date and stop.
Step 3 — Assess staleness
For each changed area, check whether the relevant docs/ file or CLAUDE.md is now stale. Look for:
- Renamed/moved/deleted classes, projects, or files that docs reference by path
- Changed workflows, request pipelines, background jobs
- New or removed endpoints, integrations, configuration keys
- New projects/modules with no corresponding doc
- Changed build/test commands or conventions in CLAUDE.md
- Stale paths in docs/code-map.md: verify every entry-point path in the table still exists (
ls or git ls-files); fix moved/renamed paths and add rows for new domain concepts introduced since the baseline
- docs/data-model.md: new/removed/renamed core entities or changed relationships (check changes under entity/domain folders and migrations)
- docs/integrations.md: new or removed external integrations, changed protocols/auth, changed job schedules
- docs/decisions.md: if the diff shows a significant new technical choice (new library, new pattern, architectural exception), propose a dated entry and ask the user to confirm the reasoning
- docs/glossary.md / docs/gotchas.md: only flag if changed code contradicts an existing entry; never invent new gotchas from the diff alone — ask the user instead
Ignore trivial changes: formatting, minor refactors that don't change behavior or structure, dependency bumps without API impact.
Step 4 — Propose, then apply
Present a list of proposed doc updates: which file, what changes, and which commits caused them. STOP and wait for confirmation.
After confirmation, apply the updates.
For newly inferred business logic, flag assumptions with <!-- VERIFY --> comments, same as initial generation.
Update docs/README.md (the index) if files were added or removed.
Write the current HEAD hash to docs/.last-sync:
git rev-parse HEAD > docs/.last-sync
Include docs/.last-sync in the same commit as the doc updates, so the baseline only advances on a real sync.
Notes
- The
.last-sync marker makes the baseline robust against typo-fix commits in docs/ that would otherwise skip undocumented code changes.
- If
docs/ does not exist at all, tell the user to run the create-docs skill first.
1---2name: update-docs3description: Sync CLAUDE.md and the docs/ knowledge base with code changes since the last documentation update. Use whenever the user asks to update docs, refresh documentation, sync docs with recent commits, check if docs are stale, or after merging changes — including phrases like "update the docs", "are the docs up to date", "sync documentation with the latest commits", or when the user names a specific commit range or PR to document.4---56# Update Docs78Detect code changes since the last documentation sync and update CLAUDE.md / docs/ accordingly. This is a two-phase workflow: **propose → confirm → apply**. Never modify docs before the user confirms.910## Step 1 — Find the baseline1112Determine the last commit where docs were in sync, in this priority order:13141. **User-specified range**: if the user names a commit, tag, or PR (e.g. "diff from abc1234", "only PR #456"), use that and skip auto-detection.152. **Marker file**: if `docs/.last-sync` exists, read the commit hash from it.163. **Fallback**: last commit that touched docs/:1718 ```bash19 git log --oneline -1 -- docs/ CLAUDE.md20 ```2122## Step 2 — Collect changes since the baseline2324```bash25git diff <baseline>..HEAD --stat -- ':!docs' ':!CLAUDE.md'26git log --oneline <baseline>..HEAD -- ':!docs' ':!CLAUDE.md'27```2829If there are no changes, tell the user the docs are already up to date and stop.3031## Step 3 — Assess staleness3233For each changed area, check whether the relevant docs/ file or CLAUDE.md is now stale. Look for:3435- Renamed/moved/deleted classes, projects, or files that docs reference by path36- Changed workflows, request pipelines, background jobs37- New or removed endpoints, integrations, configuration keys38- New projects/modules with no corresponding doc39- Changed build/test commands or conventions in CLAUDE.md40- **Stale paths in docs/code-map.md**: verify every entry-point path in the table still exists (`ls` or `git ls-files`); fix moved/renamed paths and add rows for new domain concepts introduced since the baseline41- **docs/data-model.md**: new/removed/renamed core entities or changed relationships (check changes under entity/domain folders and migrations)42- **docs/integrations.md**: new or removed external integrations, changed protocols/auth, changed job schedules43- **docs/decisions.md**: if the diff shows a significant new technical choice (new library, new pattern, architectural exception), propose a dated entry and ask the user to confirm the reasoning44- **docs/glossary.md / docs/gotchas.md**: only flag if changed code contradicts an existing entry; never invent new gotchas from the diff alone — ask the user instead4546Ignore trivial changes: formatting, minor refactors that don't change behavior or structure, dependency bumps without API impact.4748## Step 4 — Propose, then apply49501. Present a list of proposed doc updates: which file, what changes, and which commits caused them. **STOP and wait for confirmation.**512. After confirmation, apply the updates.523. For newly inferred business logic, flag assumptions with `<!-- VERIFY -->` comments, same as initial generation.534. Update `docs/README.md` (the index) if files were added or removed.545. Write the current HEAD hash to `docs/.last-sync`:5556 ```bash57 git rev-parse HEAD > docs/.last-sync58 ```59606. Include `docs/.last-sync` in the same commit as the doc updates, so the baseline only advances on a real sync.6162## Notes6364- The `.last-sync` marker makes the baseline robust against typo-fix commits in docs/ that would otherwise skip undocumented code changes.65- If `docs/` does not exist at all, tell the user to run the create-docs skill first.
haitranatwork