skill-doc-sync

What this skill does

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.


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

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

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

**Risky categories (require user approval):**
- Sections with headings containing: "Philosophy", "Principles", "Vision", "Mission", "Security", "Threat Model", "Architecture Decision"
- Paragraphs that express opinion, strategy, or rationale (not just facts)
- Content under `## Why` or `## Rationale` headings
- Any changes to `SECURITY.md` or `CONTRIBUTING.md` beyond version bumps

**WHY:** Narrative and philosophy sections reflect human judgment. Silently rewriting them risks misrepresenting the project's intent.

When risky changes are detected, present them to the user:
```
The following doc sections may need updating but contain narrative/philosophy content.
I will NOT auto-edit these. Please review and confirm each change:

1. README.md ## Philosophy — mentions "single-binary deployment" but diff adds Docker support
2. SECURITY.md ## Threat Model — new auth endpoint not documented

Approve changes? (list numbers to approve, or "skip all")
```


## Step 5: CHANGELOG Voice Polish

Apply the "sell test" to every CHANGELOG entry: **"Would a user reading this bullet think 'oh nice, I want to try that'?"**

**Rules:**
- Lead with the user benefit, not the implementation detail
- Use active voice ("Add X" not "X was added")
- Keep bullets under 120 characters
- Never delete existing CHANGELOG entries (append only)
- Group by: Added, Changed, Fixed, Removed (Keep a Changelog format)

**Example transformations:**
```
BAD:  "Refactored spawn_agent to use parameter expansion instead of basename"
GOOD: "Speed up agent spawning by eliminating 750 subshell forks (92% reduction)"

BAD:  "Added SUPPORTS_MCP_ELICITATION flag"
GOOD: "Support MCP elicitation for richer interactive prompts (CC v2.1.76+)"
```

**WHY:** The CHANGELOG is marketing copy for developers. Every bullet should make someone want to upgrade.


## Step 6: Cross-Doc Consistency

Check that key values are aligned across all documentation files.

**Consistency checks:**
- Version numbers match across `README.md`, `CLAUDE.md`, `package.json`, `CHANGELOG.md`, and any other files referencing the current version
- Feature lists in README match what is actually implemented (cross-reference with command/skill directories)
- Badge URLs and shield.io references are up to date
- Links between docs are not broken (relative path references)
- Command counts and skill counts match actual directory listings

```bash
# Example: check version consistency
PKG_VERSION=$(grep '"version"' package.json | head -1 | sed 's/.*"version": *"//' | sed 's/".*//')
echo "package.json version: $PKG_VERSION"

# Check README mentions this version
if ! grep -q "$PKG_VERSION" README.md 2>/dev/null; then
  echo "WARNING: README.md does not mention version $PKG_VERSION"
fi

# Check CHANGELOG has an entry for this version
if ! grep -q "$PKG_VERSION" CHANGELOG.md 2>/dev/null; then
  echo "WARNING: CHANGELOG.md has no entry for version $PKG_VERSION"
fi
```


## Step 7: Discoverability Check

Ensure every documentation file is reachable from `README.md` or `CLAUDE.md`. Orphaned docs are invisible docs.

**Check:**
- Every `.md` file in the project should be linked from either `README.md` or `CLAUDE.md` (directly or transitively through another linked doc)
- Flag orphaned docs that have no inbound links
- Suggest where to add links for orphaned docs

**WHY:** Documentation that cannot be found does not exist from the user's perspective. Every doc must be one or two clicks from the entry points.


## Step 8: TODOS.md Update

Update the project's task tracking based on the diff.

**Actions:**
- Mark completed items: scan TODO/FIXME/HACK comments that were removed in the diff and mark corresponding items as done
- Flag new deferred work: scan TODO/FIXME/HACK comments that were added in the diff and create new tracking entries
- Update completion percentages if the project uses progress tracking

```bash
# Find new TODOs added in the diff
NEW_TODOS=$(echo "$DIFF_FULL" | grep '^+' | grep -iE 'TODO|FIXME|HACK' | grep -v '^+++' || true)
if [[ -n "$NEW_TODOS" ]]; then
  echo "New TODOs found in diff:"
  echo "$NEW_TODOS"
fi

# Find TODOs removed in the diff
REMOVED_TODOS=$(echo "$DIFF_FULL" | grep '^-' | grep -iE 'TODO|FIXME|HACK' | grep -v '^---' || true)
if [[ -n "$REMOVED_TODOS" ]]; then
  echo "Resolved TODOs (removed in diff):"
  echo "$REMOVED_TODOS"
fi
```


## Step 9: Commit Doc Changes

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-