docs-updater

Docs updater

ドキュメントの記述とコードの動作に食い違いがないか確認し、ドキュメントを修正します。正しいのはコードです。コードにない機能、コマンド、機能を決して作り上げないでください。

開始時に宣言：「ドキュメントをコードに合わせるため、docs-updater スキルを使用します。」

シェルスニペットは bash（Windows では Git Bash）で実行してください。

0. 設定

このスキルは docs/agents/docs.md、docs/agents/workspace.md、 docs/agents/issue-tracker.md、docs/agents/human-follow-up.md を読み込みます。これらを読み込み、不足しているものがあれば補完するには、 .agents/skills/docs-updater/settings/README.md に従ってください。定義はその隣にあります。

1. モードと対象範囲

引数または呼び出し元の指示から、モードと対象範囲の両方を指定します。

• モード — fix（既定）はドキュメントを編集し、check は編集せず、食い違いを報告します。
• 対象範囲 — 差分範囲（<base>..HEAD）、変更の一覧、または全件監査を行う場合は指定しません（すべての Doc map 項目が対象です）。

呼び出し元が制約を追加する場合は、それに従ってください。ship の場合：ブランチはまだマージされていないため、ship-owned ドキュメントには手を加えず、作業がリリース済みだと主張しないでください。ロードマップ、アーカイブ、リリースまたはマージの状況、ボードの変更についても記載しないでください。ブランチが実装する内容の説明は対象範囲内です。end-session の場合：セッションの作業について、マージ済みかどうかにかかわらず、その指示に従ってください。

2. 対象ドキュメントを見つける

差分範囲の場合：

git diff --stat "$range"
git diff --name-status "$range"

ファイル一覧だけでなく、差分そのものを読んでください。生成されたコピー（Generated-config check が再生成するミラー）は対象外とし、代わりにそのソースを読んでください。Doc map で frozen とされているスキルの本文も対象外です（インストール済みで、ここでは編集しません）。名前が変更された設定や新しいコマンドなど、変更が他のドキュメントの記述にどう影響するかだけを確認してください。リポジトリが独自のスキルをインストールする場合、インストール済みのコピーは対象外としますが、そのコピーの元になった作成元は対象に含めます。各変更を Doc map の各項目の when と照合してください。対象となるパスと変更の種類（新しいエンドポイント、変更されたコマンド、新しい設定、削除された機能）を確認します。when は手がかりであって、制限ではありません。明らかに対象外のドキュメントにも影響する変更は対象に含め、レポートで名前を挙げて Doc map を拡張できるようにしてください。単なるリファクタリングであれば、ドキュメントの修正は不要なことがあります。修正を捏造せず、その旨を記載してください。変更の一覧が指定された場合も、同じ方法で照合します。全件監査の場合は、すべての項目が対象です。

次に、差分で削除または名前が変更された名前（設定、コマンド、ファイル、フラグ、「4 つすべて」のような件数）と、意味が拡大または縮小された名前を検索してください。それらへの古い参照は、どの when も予測しない食い違いです。差分で列挙された集合に要素（マーカー、設定、スキルなど）が追加された場合は、代わりに同じ集合の他の要素を検索してください。それらを列挙しているものの、新しい要素を含まない一覧は不完全になっています。一般語に埋もれないよう、ドキュメントに記載されている表記（通常はバッククォートで囲まれた `frozen`）で名前を検索してください。Doc map の範囲を超えて、生成されたコピーと frozen ドキュメントを除き、次を検索してください。

• 追跡対象のすべての Markdown ファイル（git ls-files '*.md'）；
• チェックアウトが存在する場合は、独自のルートからそのコンパニオン；
• 各 wiki：Follow-up wiki と、変更がデフォルトブランチにある場合に wiki 内にある Doc map 項目。スクラッチ領域に読み取り専用クローンを作成して検索します。

Doc map にないドキュメントで見つかった箇所も、他と同じように修正し、レポートで名前を挙げて Doc map を拡張できるようにしてください。wiki はマージ後に確認します。変更がまだマージされていないブランチを対象とする実行（ship からのすべての実行を含む）では、wiki の検索をスキップし、マージ後に検索が必要であることを報告します。次の end-session、またはデフォルトブランチでの実行時に検索し、見つかった箇所を修正します。

3. 各ドキュメントをコードと照合する

対象範囲の各ドキュメントを読み、その後、変更によって影響を受ける可能性のある主張をすべて、その根拠となる情報源と照合します。根拠は Drift probes とし、それ以外はコード、マニフェスト、設定、CI ワークフローそのものです。実行可能な設定は説明文より優先されます。ドキュメントに記載された数をそのまま信じず、プローブが列挙したものを数えてください（CI ジョブはすべての name: ではなく、トップレベルのキーで数えます）。

対象範囲を指定した実行では、範囲外で見つかったドリフト（プローブと矛盾する古い主張）を、修正せずに報告します。そのドリフトは、それ自体の変更で扱うものです。全体監査では修正します。

関連ドキュメント。 Private companion が設定されている場合、読み取りや編集を始める前にそのチェックアウトが必要です。また、専用のルートから確認します（git -C private status、git -C private log）。外側のリポジトリの履歴は、その根拠にはなりません。チェックアウトがない場合は、公開ドキュメントを確認し、実行できなかった関連ドキュメントのチェックを報告します。代わりのものは作成しません。

4. 修正（修正モード）

ドリフトのある各ドキュメントを、そのマーカーに従って編集します。

• frozen — 編集してはいけません。append-only — 追加のみ行い、変更してはいけません。amend-only — 日付入りの修正注記を追加します。
• owner-only — ドリフトを報告し、ユーザーに編集を委ねます。
• ship-owned — ship に委ねます。ship 以外では、Unreleased の変更履歴項目を追加する場合でも最大 1 件とし、バージョン、日付、日付入りセクションは追加してはいけません。
• pinned — 別のチェックでフィンガープリントが照合されます。リンクの変更であっても、名前が記載されたピンを更新するまで、その編集はチェックに失敗します。変更上必要な場合に限って編集してください。まず、編集によってピンが保護するもの（要件、マトリックスの行）が変わらないことを確認し、同じ変更内でピンを更新します。呼び出し元の PR で理由を説明できるよう、レポートには両方を記載してください。対象範囲内にある pinned ドキュメントを編集する必要がない場合は、ピンを維持します。その場合もピンが一致していることを確認し、最新であることを報告してください。

次の読者がドキュメントを信頼できるように記述します。

• 事実ごとに記載箇所は 1 つ。 事実は Doc map が指定する場所で更新し、他の場所からはそこを参照するようにします。AGENTS.md を読み込む CLAUDE.md のような簡潔な入口には、独自の内容を追加しません。
• 計画ではなく現状を記載する。 プロジェクトガイドには、実装済みの動作を記述します。ステータス、次の手順、ToDo などの作業状況は issue で管理し、Markdown には書きません。ドキュメントには結果としての契約（「シークレットは vault に保管されています」など）は記載できますが、未完了の作業は記載しません。
• 今後も有効なルールを記載する。 履歴は変更履歴と ADR に記録します。ドキュメントには現在のルールを記載し、それを定めた issue を引用してもかまいません。調査結果と、それを基にした設計が併記されているドキュメントでは、現在の状態に関する記述を更新し、日付入りの調査結果はそのまま残します。コードによって解消されたことが確認できる場合に限り、既知の制限を削除します。
• 決定事項と言葉遣い。 承認済み ADR をコードに合わせて編集してはいけません。矛盾を報告します。用語集（CONTEXT.md）で用語が定義されている場合は、定義を繰り返さず、その用語集を参照します。また、新しい用語に合わせてコードの名前を変更してはいけません。
• 非公開情報を非公開に保つ。 Doc map の 公開ドキュメントに記載しない リストにある内容、シークレット、認証情報、アカウント識別子、稼働中のリソース名、コンパニオンへのリンクは、公開ドキュメントに記載してはいけません。セキュリティ上の弱点は、公開ページではなく必ず Security findings の手順で扱います。
• 生成ファイル。 生成されたコピーではなくソースを編集し、その後 Generated-config check の再生成コマンドを実行します。依頼がない限り、エージェントとスキルのフロントマターは変更しません。
• セットアップ手順を変更するのは、前提条件、コマンド、ポートが実際に変わった場合に限ります。

すべての編集を、公開チェックアウトとコンパニオンの両方でコミットせずに残します。コミットは呼び出し元、またはスキルを単独で実行した場合はユーザーが行います。

5. 人による対応

変更後に必要となる人による対応（アクセス設定、ダッシュボードの変更、認証情報、手動確認など）をすべて列挙するか、必要な対応がないことを明記します。ship または end-session から実行した場合は、一覧を呼び出し元に返します。呼び出し元が、すべての対応についてフォローアップ手順を一度実行します。単独で実行した場合は、.agents/skills/docs-updater/settings/human-follow-up.md の ## Procedure を自分で実行します。いずれの場合も、フォローアップをドキュメントに記載するだけで終わらせてはいけません。

6. 検証

• Docs validation。各コマンドは、指定がない場合はリポジトリのルートで実行します。
• Generated-config check。設定で実行が指定されている場合に実行します。
• 空白エラーがないか git diff --check で確認します。
• 編集したすべてのドキュメントで、リンクとアンカーが解決できることを確認します。相対パスの参照先が存在し、#anchors がリンク先の見出しと一致している必要があります。

今回の編集が原因で失敗した場合は、報告する前に修正します。実際の失敗を抑制したり、回避したりしてはいけません。失敗を報告します。

7. 報告

どちらのモードでも、まず非公開コンテンツの漏えいを報告します。次に、各ドキュメントについて、プレーンテキストのラベルを付けて1行ずつ報告します。

• current — コードと照合済みで、変更は不要です。
• changed — 変更内容（修正モードの場合）。
• drift — 相違点と、その根拠となる情報源。チェックモードでは未修正のままにしたもの、コードだけでは解決できないもの（機能が無効化または削除された可能性があるもの）、または owner-only や frozen のドキュメントが該当します。

その後、どの Doc map 項目の when にも該当しなかった変更、人による対応の一覧（単独で実行した場合は、そのフォローアップリンクまたは公開を妨げる要因も含む）、検証結果、実行できなかった関連チェックを報告します。また、編集内容が未コミットであることも伝えます。