/update-docs
Keep documentation in sync with code. Detects what changed, updates the right tiers, leaves changes staged for review.
How it works
1. Detect changes → git diff vs main (or vs HEAD if standalone)
2. Classify → categorize files into doc tiers
3. Update → edit relevant docs per tier
4. Verify stats → run stats tools, refresh counts
5. Stage → git add (no commit — let parent commit per-phase)
Bundling behavior
When called from /ship (Phase D):
- Apply doc updates
- Stage changes (
git add)
- Do NOT commit — let
/ship commit as docs(<scope>): sync documentation
- Return summary of what was updated
When called standalone:
- Apply doc updates
- Commit as
docs: update documentation
Phase 1: Detect Changes
BRANCH=$(git branch --show-current)
BASE=$(git merge-base origin/main HEAD 2>/dev/null || echo HEAD~5)
git diff --name-only $BASE..HEAD
git diff --name-only HEAD # also include unstaged
Phase 2: Documentation Tiers
| Tier |
Files |
Trigger |
| 1 Core |
README.md, CLAUDE.md, top-level package READMEs |
Any significant change |
| 2 Architecture |
docs/architecture.md, docs/database-schema.md |
Structural changes |
| 3 Journey |
docs/journey/*.md (user flows) |
Business logic changes |
| 4 Claude Config |
.claude/rules/*.md, .claude/skills/**/references/*.md |
Tool/workflow changes |
Phase 3: Stats Verification
If your project has a stats sync tool, run it first — it's the single source of truth for counts in README/CLAUDE.md.
# Example — replace with your project's tool
bun run tools/stats-sync.ts --update # writes diffs into core docs
bun run tools/stats-sync.ts # check-only mode for CI
If no automated tool, verify common counts manually:
# Components, endpoints, tests — adjust globs to your structure
find src/components -name "*.tsx" | wc -l
grep -rcE "@(Get|Post|Patch|Delete|Put)\(" --include="*.ts" src/api/
Phase 4: Per-Change Update Checklist
| Change type |
Update |
| New feature |
README features list, relevant journey doc, CLAUDE.md if it affects how AI agents work |
| New API endpoint |
API doc / journey doc with endpoint table, CLAUDE.md endpoint count |
| New component |
Component README, design system doc if it introduces a pattern |
| Database change |
docs/database-schema.md, migration notes, related journey docs |
| Config change |
Doc that explains the config option, rule files that reference it |
| Refactor |
Update file paths in any doc that linked to moved/renamed files |
| Dependency upgrade |
CHANGELOG, README if version is documented |
Phase 5: Stage & Report
git add README.md CLAUDE.md docs/ .claude/
Report format:
Documentation Update — Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scope: <auto-detected files>
Updated: path/to/doc.md — what changed
Verified: Components: X | Tests: X | Endpoints: X
Skipped: path/to/doc.md — already up to date
Manual: path/to/doc.md — needs human review (reason)
Guidelines
- Concise — lead with the answer, not the context
- Scannable — tables, bullet lists, headers
- Cross-reference, don't duplicate — link to related docs
- Match code reality — every code example, path, count must match the current code
- Stage everything, commit nothing when called from
/ship
Exit conditions
- All affected tiers updated, OR
- Reported as "no doc-worthy changes" if diff is purely internal (formatting, comments, test-only)
- Manual-review items flagged with reason
1---2name: update-docs3description: Sync documentation with code changes. Auto-detects scope from git diff, updates tier 1-4 docs (core, architecture, journey, config), verifies stats. Phase D of /ship pipeline.4---56# /update-docs78Keep documentation in sync with code. Detects what changed, updates the right tiers, leaves changes staged for review.910## How it works1112```131. Detect changes → git diff vs main (or vs HEAD if standalone)142. Classify → categorize files into doc tiers153. Update → edit relevant docs per tier164. Verify stats → run stats tools, refresh counts175. Stage → git add (no commit — let parent commit per-phase)18```1920## Bundling behavior2122When called from `/ship` (Phase D):23- Apply doc updates24- Stage changes (`git add`)25- Do NOT commit — let `/ship` commit as `docs(<scope>): sync documentation`26- Return summary of what was updated2728When called standalone:29- Apply doc updates30- Commit as `docs: update documentation`3132## Phase 1: Detect Changes3334```bash35BRANCH=$(git branch --show-current)36BASE=$(git merge-base origin/main HEAD 2>/dev/null || echo HEAD~5)37git diff --name-only $BASE..HEAD38git diff --name-only HEAD # also include unstaged39```4041<!-- CONFIGURE: Adjust exclude patterns for your project (e.g., lockfiles, generated files) -->4243## Phase 2: Documentation Tiers4445| Tier | Files | Trigger |46|------|-------|---------|47| 1 Core | `README.md`, `CLAUDE.md`, top-level package READMEs | Any significant change |48| 2 Architecture | `docs/architecture.md`, `docs/database-schema.md` | Structural changes |49| 3 Journey | `docs/journey/*.md` (user flows) | Business logic changes |50| 4 Claude Config | `.claude/rules/*.md`, `.claude/skills/**/references/*.md` | Tool/workflow changes |5152<!-- CONFIGURE: Replace tier paths to match your project's doc layout. Remove tiers you don't use. -->5354## Phase 3: Stats Verification5556If your project has a stats sync tool, run it first — it's the single source of truth for counts in README/CLAUDE.md.5758```bash59# Example — replace with your project's tool60bun run tools/stats-sync.ts --update # writes diffs into core docs61bun run tools/stats-sync.ts # check-only mode for CI62```6364<!-- CONFIGURE: Replace with your stats sync command, or remove if you don't track counts in docs -->6566If no automated tool, verify common counts manually:6768```bash69# Components, endpoints, tests — adjust globs to your structure70find src/components -name "*.tsx" | wc -l71grep -rcE "@(Get|Post|Patch|Delete|Put)\(" --include="*.ts" src/api/72```7374## Phase 4: Per-Change Update Checklist7576| Change type | Update |77|-------------|--------|78| New feature | README features list, relevant journey doc, CLAUDE.md if it affects how AI agents work |79| New API endpoint | API doc / journey doc with endpoint table, CLAUDE.md endpoint count |80| New component | Component README, design system doc if it introduces a pattern |81| Database change | `docs/database-schema.md`, migration notes, related journey docs |82| Config change | Doc that explains the config option, rule files that reference it |83| Refactor | Update file paths in any doc that linked to moved/renamed files |84| Dependency upgrade | CHANGELOG, README if version is documented |8586<!-- CONFIGURE: Add change types specific to your project -->8788## Phase 5: Stage & Report8990```bash91git add README.md CLAUDE.md docs/ .claude/92```9394Report format:9596```97Documentation Update — Summary98━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━99Scope: <auto-detected files>100Updated: path/to/doc.md — what changed101Verified: Components: X | Tests: X | Endpoints: X102Skipped: path/to/doc.md — already up to date103Manual: path/to/doc.md — needs human review (reason)104```105106## Guidelines107108- **Concise** — lead with the answer, not the context109- **Scannable** — tables, bullet lists, headers110- **Cross-reference, don't duplicate** — link to related docs111- **Match code reality** — every code example, path, count must match the current code112- **Stage everything, commit nothing** when called from `/ship`113114## Exit conditions115116- All affected tiers updated, OR117- Reported as "no doc-worthy changes" if diff is purely internal (formatting, comments, test-only)118- Manual-review items flagged with reason
cloverink