Akshaysanthosh/docs-drift-check

Docs Drift Check (ドキュメント乖離チェック)

ブランチや差分がドキュメントの乖離を引き起こした可能性があるかを判定し、確認すべき正確なドキュメントファイルと用語を指摘します。このスキルは、広範な推測ではなく、差分からの具体的な証拠に偏るべきです。

このスキルを使用するタイミング

• ユーザーがブランチ、PR、ローカル変更にドキュメント更新が必要かどうかを尋ねたとき。
• 差分がAPIルート、CLIフラグ、環境変数、設定キー、セットアップ手順、ファイル/モジュール名など、公開向けの動作を変更する場合。
• README、docs/、examples/、オンボーディング、セットアップドキュメントの乖離をレビューするタスクのとき。

このスキルは、純粋なスタイル変更、テストのみの変更、または目に見える動作変更のない明らかに内部的なリファクタリングには使用しないでください。

クイックスタート

1. ヘルパーを実行します: bash .agents/skills/docs-drift-check/scripts/docs_drift_check.sh [base-ref]
2. 最もシグナルの高いセクションから読みます:
   • 潜在的なリネーム
   • 環境変数の変更の可能性
   • CLIフラグの変更の可能性
   • ルートまたはエンドポイントの変更の可能性
   • 設定の変更の可能性
3. 最も可能性の高いドキュメントターゲットを調査します:
   • README.md
   • docs/
   • examples/
   • 影響を受ける機能の近くにあるセットアップまたはオンボーディングドキュメント
4. 以下の内容を含む短い結果を返します:
   • リスクレベル: 低, 中, 高
   • 差分からの具体的な証拠
   • 影響を受ける可能性のあるドキュメントファイル
   • 推奨される編集またはパッチ計画

ワークフロー

1. 比較基準を確立する

• ユーザーが指定したベース参照を優先します。
• 指定がない場合、ヘルパーはデフォルトで main を使用します。
• ベース参照が存在しない場合は、その旨を明確に伝え、正しいブランチまたは比較ターゲットを尋ねます。

2. ドキュメントに影響する変更を特定する

以下の高シグナルの変更タイプに焦点を当てます:

• 環境変数
• CLIフラグとコマンド
• APIルートまたはエンドポイント
• 設定キー
• リネームされたファイルまたはモジュール
• セットアップまたはオンボーディング手順

まずヘルパースクリプトを使用して決定的な一次パスを実行し、必要に応じて手動で差分を調査します。

3. コード変更をドキュメントと比較する

• 古い名前と新しい名前、パス、フラグ、ルート、設定用語についてドキュメントを検索します。
• リポジトリ全体をスキャンする前に、変更領域に最も近いドキュメントを優先します。
• シグナルのルーブリックや出力形式が必要な場合は、references/heuristics.md を参照してください。

4. 結果を分類する

• 低: ドキュメントは問題ない可能性が高い、または弱いシグナルのみで古い参照が見つからない場合。
• 中: 乖離の可能性がある、または公開サーフェスの強い変更があるが古いドキュメントが確認されていない場合。
• 高: 特定の古い用語、パス、欠落した手順があり、乖離が確認された、またはその可能性が高い場合。

5. 出力を簡潔に保つ

以下の形式を使用します:

1. リスクレベル
2. 理由
3. 影響を受けるドキュメントファイル
4. 推奨される編集

ルール

• 意味的な推測よりも、差分からの決定的な証拠を優先します。
• 具体的な古い参照、欠落したドキュメント更新、またはリネームされたパスを指摘できない限り、確認された乖離を主張しないでください。
• 証拠が部分的である場合は、確実性を過大評価せずに「乖離の可能性あり」と述べてください。
• 書式のみ、コメントのみ、テストのみの変更は、ユーザー向けの動作を変更しない限り無視してください。
• 結果を短く、実行可能に保ってください。