doc-updates

ドキュメント更新ワークフロー

使用する場面

コードの変更に伴い、README、計画書、Wiki、または docstring の更新が必要な場合に、このスキルを使用します。変更のコンテキストを把握するため、最初に Skill(sanctum:git-workspace-review) を実行してください。

システムの機能

ドキュメント更新ワークフローには、複数の専門的な機能が含まれています。統合の検出によって重複を特定し、ディレクトリごとのスタイルルールを適用します。docs/ には厳格な制限を、book/ ディレクトリにはより緩やかな制限を設けています。また、バージョン番号とコンポーネント数の正確性を検証し、対応バージョンの Claude Code では LSP と連携して、ドキュメントの意味的な正確性を検証します。

使用しない場面

• README 固有の更新 — 代わりに update-readme を使用します
• 複雑な複数ファイルの統合 — doc-consolidation を使用します

必須の進捗項目

1. doc-updates:context-collected - Git コンテキスト + CHANGELOG の確認
2. doc-updates:targets-identified
3. doc-updates:consolidation-checked（スキップ可能）
4. doc-updates:edits-applied
5. doc-updates:guidelines-verified
6. doc-updates:slop-scanned - scribe による AI マーカーの検出
7. doc-updates:plugins-synced - plugin.json とディスクの監査
8. doc-updates:capabilities-synced - plugin.json とドキュメントの同期
9. doc-updates:accuracy-verified
10. doc-updates:preview

ステップ 1：コンテキストを収集する（context-collected）

• Skill(sanctum:git-workspace-review) が実行済みであることを確認します。
• そのメモを使って差分を把握します。
• ドキュメントの更新が必要な機能やバグ修正を特定します。

CHANGELOG の参照（バージョン同期に重要）：

# Check recent CHANGELOG entries for undocumented features
head -100 CHANGELOG.md

# Compare documented version vs plugin versions
grep -E "^\[.*\]" CHANGELOG.md | head -3
for p in plugins/*/.claude-plugin/plugin.json; do
    jq -r '"\(.name): \(.version)"' "$p"
done | head -5

CHANGELOG の項目を次と照合します。

• book/src/reference/capabilities-reference.md - すべてのスキル／コマンド／エージェント
• book/src/plugins/ のプラグインドキュメント - プラグインごとのドキュメント
• プラグインの README - クイックリファレンスドキュメント

ステップ 2：対象を特定する（targets-identified）

• 対象範囲内にある、関連するファイルをすべてのドキュメントの場所から一覧にします。
  • docs/ - リファレンスドキュメント（厳格なスタイル）
  • book/ - 技術書のコンテンツ（緩やかなスタイル）
  • プロジェクトおよびプラグインのルートにある README.md ファイル
  • 存在する場合は wiki/ の項目
  • コードファイル内の docstring
• まずユーザー向けドキュメントを優先し、次に補助的な計画書や仕様書を確認します。
• アーキテクチャに関する作業を計画している場合は、wiki/architecture/（または ADR が配置されている場所）に Architecture Decision Record（ADR）がすでに存在するか確認します。
• 不足している ADR は、実装を始める前に対象一覧へ追加します。

ステップ 2.5：統合を確認する（consolidation-checked）

読み込み：@modules/consolidation-integration.md

目的：編集前に重複や肥大化を検出します。

確認対象：

• 未追跡のレポート（大文字表記の *_REPORT.md、*_ANALYSIS.md ファイル）
• 肥大化したコミット済みドキュメント（docs/ で 500 行超、book/ で 1000 行超のファイル）
• 古くなったファイル（削除すべき古いコンテンツ）

以下を行う前にユーザーの承認が必要です：

• あるファイルのコンテンツを別のファイルに統合する
• 古くなったファイルや重複ファイルを削除する
• 肥大化したファイルを分割する

スキップ方法：

• --skip-consolidation フラグを使用すると、このフェーズをスキップできます
• すべてを処理する代わりに、特定の項目を選択できます

完了条件：すべての統合候補について、ユーザーが承認またはスキップしていること。

ステップ 3：編集を適用する（edits-applied）

• 根拠に基づく表現で各ファイルを更新し、何が変わったか、またその理由を説明します。
• 可能な場合は、具体的なコマンド、ファイル名、または設定オプションを記載します。
• docstring には命令形を使い、簡潔に保ちます。
• ADR については、完全なテンプレート構成、ステータスの流れ、不変性のルール、ベストプラクティスが記載された modules/adr-patterns.md を参照します。

ステップ 4：ガイドラインを適用する（guidelines-verified）

読み込み：@modules/directory-style-rules.md

スタイルの徹底

ディレクトリ固有のルールを適用して、ドキュメントの一貫性を保ちます。システムは「in order to」や「it should be noted」などの埋め草の表現を検出して削除し、技術文書の本文に絵文字が含まれていないことを確認します。曖昧な主張ではなく具体的な参照を用いた根拠のある表現にし、指示には命令形を使います。3項目以上のリストでは、読みやすさを高めるため、文章ではなく箇条書きを優先します。

監査では、段落が長さの上限を超えている場合や、ファイルが定められた行数のしきい値を超えている場合に警告が出ます。また、プロジェクトのドキュメント全体で技術的かつ直接的な語調を保つため、宣伝文句や「capable」「smooth」のような抽象的な形容詞にもフラグを立てます。

ステップ 4.25：AI スロップの検出（slop-scanned）

編集したドキュメントに対して Skill(scribe:slop-detector) を実行し、AI 生成コンテンツの特徴を検出します。

Scribe の統合

scribe プラグインは、AI スロップを徹底的に検出します。

Skill(scribe:slop-detector) --target [edited-files]

次の項目を検出します。

• Tier 1 の単語：delve、tapestry、comprehensive、leveraging など
• フレーズのパターン：「今日の変化の速い世界では」「どれほど重要かは言い尽くせません」
• 構造上の特徴：過剰な em ダッシュ、箇条書きの多用、文の均一性
• 迎合的なフレーズ：「喜んでお手伝いします」「すばらしい質問です！」
• 句読点の代用：スペースを挟んだ --、「and」の代わりの +、セミコロンで文をつなぐ用法
• 対比的な否定：「X ではなく Y です」「X ではなく Y」「Y だけでなく、」
• 結果を付け足す表現：事実を次々と述べた後に続く「、そのため……」。1000 語あたりの密度が 2.0 を超える場合
• 修正の過剰な説明と否定的な表現：「in order to」「this ensures that」「not uncommon」や、ファイルごとの否定表現の密度

1 つのコマンドで、オプトイン項目や信頼度の低いカテゴリも含め、検出結果とファイル名、行番号をすべて特定できます。

uv run --with pyyaml python scripts/slop_score.py --audit <edited-files>

編集した .py ファイルもこの一覧に含めてください。スコアラーは Python ファイルのパスをコメントと docstring として読み込み、行番号を保持するため、検出結果から確認すべき行を特定できます。表記は文章ではありません。対応表の矢印、数式のプラス記号、コードが照合する文字として引用された文字は、docstring 内にあるコードです。

対象読者への適合

ドキュメントを書き直す前に、読者を明確にします。保守対象のドキュメントには、明示されているか想定されているかを問わず、すでに対象読者がいます。それを無視した編集をすると、誰の役にも立たないドキュメントになっていきます。

Skill(scribe:slop-detector)   # module: audience-targeting.md

• ドキュメントに対象レベルが記載されている場合は、そのレベルを確認します。記載がなければ、ドキュメントの配置場所からレベルを推定します（README と getting-started は newcomer、プラグインガイドは practitioner、ADR と詳細解説は expert）。そのうえで、レビュー担当者が修正できるよう、変更概要に推定したレベルを記載します。配置場所から判断できない場合は、推測せず、質問してください。
• セクションごとに削減テストを実施します。読者が行動を起こす前に必要な情報は残し、後で必要になる情報はリンクし、より高いレベルの読者だけが必要とする情報は切り出し、どのレベルの読者にも必要ない情報は削除します。
• 削除ではなく切り出します。対象レベルに合わない内容は、スキルの場合は modules/<topic>.md、リポジトリのドキュメントの場合は docs/deep-dive/<topic>.md に移し、親ドキュメントの冒頭から対象読者を明記する一文でリンクします。
• newcomer 向けドキュメントに expert 向けの詳細を追加する更新は、よくある逸脱です。これが、getting-started ページを率直な段落を一つずつ加えるうちにリファレンスマニュアルへ変えてしまいます。

創作物には適用しないでください。audience-targeting.md では、対象から除外する scribe:voice-* と session-to-post の対象範囲を名前を挙げて定めています。

ライティングスタイルのガイドライン

文章の品質を高めるには、elements-of-style:writing-clearly-and-concisely を確認します。

# If superpowers/elements-of-style is installed:
Skill(elements-of-style:writing-clearly-and-concisely)

# Fallback if not installed - use scribe:doc-generator principles:
Skill(scribe:doc-generator) --remediate

代替手段として、同等のガイダンスを以下に示します。

1. すべての主張を具体的な根拠で裏付けます
2. 修辞的なつなぎ表現を削ります（型にはまった書き出しや締めくくりは使いません）
3. 形容詞ではなく、数値、コマンド、ファイル名を使います
4. 箇条書きと文章のバランスを取ります
5. 執筆者の視点（トレードオフ、理由）を示します

修正

スロップスコアが 2.5（中程度）を超えた場合は、次を実行します。

Agent(scribe:doc-editor) --target [file]

ユーザーの承認を得ながら、セクションごとに対話形式でクリーンアップできます。

スキップオプション

• --skip-slop フラグを使用すると、スロップの検出をスキップできます
• スロップに関する警告は、デフォルトでは処理をブロックしません

ステップ 4.5：プラグイン登録の同期（plugins-synced）

plugin.json ファイルとディスク上の状態を照合します（登録のずれを防ぎます）。

# Quick discrepancy check for all plugins
for plugin in plugins/*/; do
  name=$(basename "$plugin")
  pjson="$plugin/.claude-plugin/plugin.json"
  [ -f "$pjson" ] || continue

  # Count commands
  json_cmds=$(jq -r '.commands | length' "$pjson" 2>/dev/null || echo 0)
  disk_cmds=$(ls "$plugin/commands/"*.md 2>/dev/null | wc -l)

  # Count skills (directories only)
  json_skills=$(jq -r '.skills | length' "$pjson" 2>/dev/null || echo 0)
  disk_skills=$(ls -d "$plugin/skills"/*/ 2>/dev/null | wc -l)

  # Report mismatches
  if [ "$json_cmds" != "$disk_cmds" ] || [ "$json_skills" != "$disk_skills" ]; then
    echo "$name: commands=$json_cmds/$disk_cmds skills=$json_skills/$disk_skills"
  fi
done

不一致が見つかった場合：/update-plugins --fix を実行するか、plugin.json ファイルを手動で更新します。

重要な理由：登録されていないコマンドやスキルは、Claude Code のスラッシュコマンドメニューに表示されず、検出もできません。

ステップ 4.75：機能ドキュメントの同期（capabilities-synced）

読み込み：@modules/capabilities-sync.md

目的：plugin.json の登録内容がリファレンスドキュメントに反映されていることを確認します。

同期対象：

ソース	ドキュメントの対象
plugin.json.skills[]	book/src/reference/capabilities-reference.md
plugin.json.commands[]	book/src/reference/capabilities-reference.md
plugin.json.agents[]	book/src/reference/capabilities-reference.md
hooks/hooks.json	book/src/reference/capabilities-reference.md
プラグインの存在	book/src/plugins/{plugin}.md

簡易チェック：

# Compare registered vs documented skills
for pjson in plugins/*/.claude-plugin/plugin.json; do
  plugin=$(basename $(dirname $(dirname "$pjson")))
  jq -r --arg p "$plugin" '.skills[]? | sub("^\\./skills/"; "") | "\($p):\(.)"' "$pjson" 2>/dev/null
done | sort > /tmp/registered-skills.txt

grep -E "^\| \`[a-z-]+\` \|" book/src/reference/capabilities-reference.md | \
  head -120 | awk -F'|' '{print $2":"$3}' | sort > /tmp/documented-skills.txt

# Show missing
comm -23 /tmp/registered-skills.txt /tmp/documented-skills.txt

相違が見つかった場合：

1. ドキュメントに記載がない場合：capabilities-reference.md の表に項目を追加します
2. プラグインのページがない場合：book/src/plugins/{plugin}.md を作成します
3. SUMMARY に記載がない場合：book/src/SUMMARY.md にプラグインを追加します

自動生成する項目の形式：

| `{skill-name}` | [{plugin}](../plugins/{plugin}.md) | {description} |

スキップオプション：--skip-capabilities を使用すると、このフェーズをスキップできます。

ステップ 5：正確性の検証（accuracy-verified）

読み込み：@modules/accuracy-scanning.md

コードベースと照合して記述内容を検証します。

# Quick version check
for p in plugins/*/.claude-plugin/plugin.json; do
    jq -r '"\(.name): \(.version)"' "$p"
done

# Quick counts
echo "Plugins: $(ls -d plugins/*/.claude-plugin/plugin.json | wc -l)"
echo "Skills: $(find plugins/*/skills -name 'SKILL.md' | wc -l)"

検証：--help フラグを付けてコマンドを実行し、利用可能であることを確認します。

不一致として検出する項目：

• plugin.json と一致しないバージョン番号
• 実際のディレクトリと一致しないプラグイン／スキル／コマンドの数
• 存在しないファイルパス

LSP を活用した検証（2.0.74 以降）：

ENABLE_LSP_TOOL=1 が設定されている場合、セマンティック分析を使って正確性の検証を強化します。

1. API ドキュメントの網羅性：

   • LSP で、すべての公開関数／クラスを照会します
   • ドキュメントがないものを確認します
   • エクスポートされたすべての項目にドキュメントがあることを検証します

2. シグネチャの検証：

   • ドキュメントに記載された関数シグネチャと実際のコードを比較します
   • パラメーターの不一致を検出します
   • 戻り値の型の相違を検出します

3. 参照の検索：

   • LSP を使って、ドキュメントに記載された項目の使用箇所をすべて検索します
   • 実際の使用例をドキュメントに含めます
   • 相互参照が正確であることを検証します

4. コード構造の検証：

   • 記載されたファイルパスが存在することを確認します（LSP の定義を使用）
   • モジュール構成がドキュメントと一致していることを検証します
   • 名前変更や移動があった項目を検出します

効率性：LSP クエリ（50 ms）は、手動でファイルをたどる場合（数分）に比べて、検証を大幅に高速化します。

デフォルトの方針：ドキュメントの更新では、すべての検証タスクでLSP を優先してください。最良の結果を得るには、ENABLE_LSP_TOOL=1 を恒久的に有効にしてください。

処理をブロックしない警告：警告は参考情報です。修正するかどうかはユーザーが判断します。

ステップ 6：変更のプレビュー（preview）

• 編集した各ファイルの差分（git diff <file> または rg のスニペット）を表示します。
• 正確性に関する警告があれば含めます。
• 次の項目をまとめます。
  • 作成／変更／削除したファイル
  • 実施した統合処理
  • 修正したスタイル違反
  • 残っている TODO またはフォローアップ事項

終了条件

• すべての進捗項目が完了し、ドキュメントが更新されていること。
• 新しい ADR がある場合は、適切なステータスと関連作業へのリンクを設定し、wiki/architecture/（または既定の ADR ディレクトリ）に配置されていること。
• ディレクトリ固有のスタイル規則が満たされていること。
• 編集した各ドキュメントで対象読者の層が明記または推定され、異なる層を対象とするセクションがないこと。
• 対象層から外れる内容は削除して層を合わせるのではなく、modules/ または docs/deep-dive/ に移し、リンクされていること。
• 正確性に関する警告に対処するか、認識したことを明記していること。
• 内容が AI 生成のように聞こえないこと。
• ファイルがステージング済み、またはレビュー可能な状態であること。

フラグ

フラグ	効果
--skip-consolidation	フェーズ 2.5 の統合チェックをスキップします
--skip-slop	フェーズ 4.25 の AI スロップ検出をスキップします
--strict	すべての警告をエラーとして扱います
--book-style	すべてのファイルに book/ の規則を適用します

トラブルシューティング

よくある問題

ドキュメントの不整合 make docs-sync-check を実行して、機能ドキュメントがプラグイン登録と引き続き一致していることを確認してください。

ビルドの失敗 必要な依存関係がすべてインストールされていることを確認してください。

リンク切れ ドキュメントファイル内の相対パスを確認してください。