echo "Found $DOC_COUNT doc files to scan (cap: 30)"
if [[ "$DOC_COUNT" -ge 30 ]]; then
echo "WARNING: Doc file cap reached (30). Some files may be skipped."
fi
```
Read each discovered doc file so you have their current content in context.
---
## Step 2: Cross-Reference Diff
Run `git diff --stat HEAD~1` (or diff against the base branch if on a feature branch) to identify which files changed and what content may now be stale in each doc.
```bash
# Get the diff stat to identify changed files
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
DIFF_STAT=$(git diff --stat HEAD~1)
DIFF_FULL=$(git diff HEAD~1)
else
BASE_BRANCH=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null)
DIFF_STAT=$(git diff --stat "$BASE_BRANCH"..HEAD)
DIFF_FULL=$(git diff "$BASE_BRANCH"..HEAD)
fi
echo "$DIFF_STAT"
```
For each doc file, check whether any paths, function names, counts, or version numbers mentioned in the doc were affected by the diff.
---
## Step 3: Auto-Update Factual Corrections
Fix paths, counts, table entries, and version numbers automatically. These are mechanical changes that do not alter meaning.
**Auto-update targets:**
- File paths that were renamed or moved in the diff
- Numeric counts (e.g., "42 tests" when the number changed)
- Version strings (e.g., `v9.5.0` when `package.json` bumped)
- Table entries referencing renamed or removed items
- Import/require paths that changed
**WHY:** Stale factual references erode trust in documentation. A user who sees a wrong path or count will doubt everything else in the doc.
---
## Step 4: Risky Change Detection
Flag narrative, philosophy, or security-related doc sections for user confirmation. Do NOT auto-edit these.
Commit all documentation changes to the current branch and update the PR body with a doc-sync summary.
```bash
# Stage only .md files that were modified by this skill
git add *.md docs/*.md 2>/dev/null || true
# Check if there are staged changes
if git diff --cached --quiet; then
echo "No documentation changes needed — all docs are up to date."
else
git commit -m "docs: post-ship documentation sync
- Auto-updated paths, counts, and version references
- CHANGELOG entries polished for user benefit
- Cross-doc consistency verified
- Discoverability check passed
"
echo "Documentation sync committed."
fi
```
If a PR exists for the current branch, update its body to include a doc-sync section:
```bash
# Update PR body with doc-sync summary (if PR exists)
PR_NUMBER=$(gh pr view --json number -q '.number' 2>/dev/null || true)
if [[ -n "$PR_NUMBER" ]]; then
echo "Updating PR #$PR_NUMBER with doc-sync summary..."
fi
```
---
## Integration
This skill is designed to work as a sub-step of `flow-deliver`. After validation and review are complete, invoke doc-sync to ensure documentation stays current with the shipped code.
