Update Documentation

Ensure all documentation matches the current code state. Updates both git-tracked docs (committed) and local-only docs (e.g., CLAUDE.md files if gitignored).

Context: the arguments provided when this skill is invoked

Phase 1: Discover What Changed

# Find the base branch
BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
BASE=${BASE:-main}

# Changed files on this branch (determines which docs to check)
CHANGED=$(git diff --name-only $(git merge-base HEAD origin/$BASE)..HEAD)
echo "$CHANGED"

Read the project's CLAUDE.md or AGENTS.md to understand documentation conventions and which files track counts.

Phase 2: Verify Structural Counts

Run the project's actual count verification commands and compare against documented values. Adapt the commands below to the project's structure.

# Tests (Python): every tracked test file, wherever the layout keeps it (top-level
# tests/, per-app tests/ packages, or test files next to the code they cover)
TEST_COUNT=$(git ls-files -z '*test_*.py' '*_test.py' | xargs -0 grep -HcE '^[[:space:]]*(async )?def test_' | awk -F: '{s+=$NF}END{print s+0}')

# Tests (JS/TS)
# TEST_COUNT=$(find src \( -name '*.test.ts' -o -name '*.spec.ts' \) -exec grep -c 'it(\|test(' {} + 2>/dev/null | awk -F: '{s+=$2}END{print s+0}')

Search documentation files for count references and compare:

for f in README.md CLAUDE.md AGENTS.md docs/*.md .claude/rules/*.md; do
  [ -f "$f" ] && grep -niE '(tests|services|routers|templates|steps|commands|pages|modules|models|subcommands)[[:space:]]*:?[[:space:]]*[0-9][0-9,]*\+?|[0-9][0-9,]*\+?[[:space:]]*(tests|services|routers|templates|steps|commands|pages|modules|models|subcommands)' "$f"
done

Also check the project's vision or roadmap doc, if AGENTS.md or README.md links one and it lives outside the paths above.

Flag any documented count that doesn't match the actual count.

Phase 3: Check Scope-Specific Docs

Based on which files changed, check related documentation:

• Source code structure changed (new files, renamed modules): verify architecture docs, module lists, project tree
• Tests added/removed: verify test counts in all docs
• CLI commands changed: verify command lists and help text references
• Configuration changed: verify config docs, env var references, default values
• API endpoints changed: verify API references, request/response shapes

Only check docs related to the changed code paths. Skip unchanged areas.

Phase 4: Apply Updates

For each stale doc:

1. Read the full current file
2. Identify the specific section(s) that need updating
3. Update only the factual content; never rewrite prose
4. Preserve the existing format and structure

Phase 5: Stage and Report

# Stage tracked docs only
git diff --name-only | grep '\.md$' | while read f; do
  git ls-files --error-unmatch "$f" 2>/dev/null && git add "$f"
done

# Show what changed
git diff --cached --stat

Report what was updated:

## Docs Updated

### Tracked (will be committed)
- <file>: <what changed>

### No changes needed
- <file>

Rules

• No approval gate: runs as an automated step
• Only update factual content: counts, lists, names, values. Never rewrite prose
• Idempotent: running twice produces no diff
• Two-tier staging: stage tracked docs; update local-only docs on disk without staging
• Minimal changes: don't reorganize or reformat docs that aren't stale
• Preserve structure: match existing format and section headers
• Scope-driven: only check docs related to changed code paths, not the entire project
• NEVER use emojis in any output