skill-doc-sync

ホスト：Codex CLI — このスキルはClaude Code向けに設計され、Codex用に適応されています。 相互参照コマンドでは、/octo:* スラッシュコマンドではなく、Codexにインストールされているスキル名を使用します。 現在のセッションで利用可能であることが確認できるまでは、プロバイダー、モデル、ホストのサブエージェントが利用可能だと断言しないでください。 ホストツールの代替手段については、skills/blocks/codex-host-adapter.md を参照してください。

リリース後のドキュメント同期

Deliverフェーズ向けのドキュメント同期を自動化します。コードがコミットされ、PRが作成された後、このスキルはプロジェクト内のすべての .md ファイルを読み込み、差分と相互参照して、事実に関する内容を自動更新し、ドキュメント間の整合性を確認して、PR本文を更新します。

上限

• スキャンするドキュメントファイルは最大30個 — 上限を超えるファイルはスキップし、ユーザーに警告します
• CHANGELOGを上書きしない — 既存の項目は削除せず、追記のみ行います
• 説明や理念に関するセクションを変更する前に、ユーザーに確認する — リスクのある変更には確認が必要です

ステップ1：ドキュメントを検出する

プロジェクトのルートから、node_modules/ と .git/ を除外し、最大深度2で .md ファイルをすべて検索します。

# 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

検出した各ドキュメントファイルを読み込み、現在の内容を把握してください。

ステップ2：差分と相互参照する

git diff --stat HEAD~1 を実行し（フィーチャーブランチの場合はベースブランチとの差分を使用）、変更されたファイルと、各ドキュメントで古くなっている可能性のある内容を特定します。

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

各ドキュメントファイルについて、記載されているパス、関数名、件数、バージョン番号が差分の影響を受けていないか確認します。

ステップ3：事実関係の修正を自動更新する

意味を変えない機械的な変更として、パス、件数、表の項目、バージョン番号を修正します。

自動更新の対象：

• 差分で名前が変更された、または移動されたファイルパス
• 数値（数が変わった場合の「42 tests」など）
• バージョン文字列（package.json の更新に伴う v9.5.0 など）
• 名前が変更または削除された項目を参照する表の項目
• 変更されたインポート／requireパス

理由： 古くなった事実関係の記載は、ドキュメントへの信頼を損ないます。誤ったパスや件数を見たユーザーは、ドキュメントに書かれているほかの内容も疑うようになります。

ステップ4：リスクのある変更を検出する

説明、理念、セキュリティに関するドキュメントのセクションを、ユーザーの確認が必要な項目として扱います。これらは自動編集しないでください。

リスクのあるカテゴリ（ユーザーの承認が必要）：

• 見出しに「Philosophy」、「Principles」、「Vision」、「Mission」、「Security」、「Threat Model」、「Architecture Decision」を含むセクション
• 事実だけでなく、意見、戦略、理由を述べている段落
• ## Why または ## Rationale 見出しの下にある内容
• バージョン更新以外の SECURITY.md または CONTRIBUTING.md の変更

理由： 説明や理念に関するセクションには、人間の判断が反映されています。これらを黙って書き換えると、プロジェクトの意図を誤って伝えるおそれがあります。

リスクのある変更を検出した場合は、ユーザーに提示してください：

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")

ステップ5：CHANGELOGの表現を磨く

すべてのCHANGELOG項目に「売り込みテスト」を適用します。「この箇条書きを読んだユーザーは、『おお、いいね。試してみたい』と思うだろうか？」

ルール：

• 実装の詳細ではなく、ユーザーにとってのメリットから始める
• 能動態を使う（「Xを追加」ではなく「Xが追加されました」）
• 箇条書きは120文字未満にする
• 既存のCHANGELOG項目は削除しない（追記のみ）
• Added、Changed、Fixed、Removedごとに分類する（Keep a Changelog形式）

変換例：

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+)"

理由： CHANGELOGは開発者向けのマーケティング文です。各項目を、アップグレードしたくなるような内容にしてください。

ステップ 6：ドキュメント間の整合性

すべてのドキュメントファイルで、重要な値に一貫性があることを確認します。

整合性チェック：

• README.md、CLAUDE.md、package.json、CHANGELOG.md および現行バージョンに言及しているその他のファイルで、バージョン番号が一致している
• README の機能一覧が実際の実装内容と一致している（コマンド／スキルのディレクトリと照合）
• バッジの URL と shield.io の参照先が最新である
• ドキュメント間のリンクが切れていない（相対パスの参照）
• コマンド数とスキル数が実際のディレクトリ一覧と一致している

# 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

ステップ 7：見つけやすさの確認

すべてのドキュメントファイルに README.md または CLAUDE.md からたどり着けるようにします。孤立したドキュメントは、存在しないも同然です。

確認項目：

• プロジェクト内のすべての .md ファイルが、README.md または CLAUDE.md から（直接、または別のリンク先ドキュメントを経由して）リンクされている
• 受信リンクのない孤立したドキュメントにフラグを立てる
• 孤立したドキュメントへのリンクを追加する場所を提案する

**理由：**ユーザーが見つけられないドキュメントは、ユーザーにとって存在しないのと同じです。すべてのドキュメントが、入口から 1、2 回のクリックでたどり着けるようにする必要があります。

ステップ 8：TODOS.md の更新

差分に基づいて、プロジェクトのタスク管理を更新します。

対応内容：

• 完了した項目に印を付ける：差分で削除された TODO/FIXME/HACK コメントを確認し、対応する項目を完了としてマークする
• 新たに先送りされた作業にフラグを立てる：差分で追加された TODO/FIXME/HACK コメントを確認し、新しい追跡項目を作成する
• プロジェクトで進捗管理を行っている場合は、完了率を更新する

# 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

ステップ 9：ドキュメントの変更をコミットする

すべてのドキュメントの変更を現在のブランチにコミットし、PR の本文をドキュメント同期の概要で更新します。

# 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

現在のブランチに PR が存在する場合は、本文にドキュメント同期セクションを追加します：

# 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

統合

このスキルは flow-deliver のサブステップとして動作するように設計されています。検証とレビューが完了したら、doc-sync を呼び出して、リリースしたコードにドキュメントを最新の状態で合わせます。

flow-deliver からの呼び出し：

After PR creation and CI passes:
1. Run doc-sync to update documentation
2. Push doc changes to the PR branch
3. Re-run CI if doc changes affect tests

単独での呼び出し：

User: "sync docs"
User: "update documentation after merge"
User: "document changes from last release"