Skill Doc Sync

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

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

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.