skill-doc-sync

Post-Ship Documentation Synchronization

Automated documentation synchronization for the Deliver phase. After code is committed and a PR is created, this skill reads all .md files in the project, cross-references the diff, auto-updates factual content, checks cross-doc consistency, and updates the PR body.

---

Caps

• Max 30 doc files scanned — skip files beyond the cap, warn the user
• Never clobber CHANGELOG — append only, never delete existing entries
• Ask user before changing narrative/philosophy sections — risky changes require confirmation

---

Step 1: Discover Docs

Find all .md files in the project root (max depth 2), skipping node_modules/ and .git/.

# Discover all markdown files (max depth 2, skip noise directories)
DOC_FILES=$(find . -maxdepth 2 -name '*.md' \
  -not -path './node_modules/*' \
  -not -path './.git/*' \
  -not -path './vendor/*' \
  -not -path './.claude/*' \
  2>/dev/null | head -30)

DOC_COUNT=$(echo "$DOC_FILES" | wc -l | tr -d ' ')
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.

# 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.