/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 the merge base with origin/main
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, the parent commits per phase)

Bundling behavior

When called from /ship (Phase D):

• Apply doc updates
• Stage changes (git add)
• Do NOT commit; /ship commits as docs(<scope>): sync documentation
• Cover everything that ships: the original work and every A/R fix round
• 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) || { echo "cannot resolve origin/main, git fetch first"; exit 1; }   # never guess a base
git diff --name-only $BASE..HEAD
git diff --name-only HEAD  # also include unstaged

Phase 2: Documentation Tiers

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

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