| name | utility-doc-audit |
| description | ドキュメント (設計書・仕様書・調査結果・README 等) の整合性・フォーマット適合を fresh context のサブエージェント fan-out で監査する。指摘のみ行い、修正はしない。「この設計書を監査して」「ドキュメントを監査して」「/utility-doc-audit docs/DESIGN.md」「文書の整合性をチェックして」などのリクエストで起動。 |
/utility-doc-audit
ドキュメントを書き手と別コンテキストの複数観点で監査し、指摘レポートを返す。書き手自身は「定義したつもり」バイアスで未定義用語・断絶した参照を検出できない。fresh context のサブエージェントに検査させることが本スキルの存在理由。
**修正はしない。指摘レポートのみ。**修正するかどうか・どう直すかは呼び出し元の判断。
入力
- 引数で対象ファイルパスを受け取る（複数可）。任意で観点の絞り込み（例: 「用語閉包だけ」）を受け付ける
- 任意で変更文脈（何をどう修正したかの概要・修正意図）を受け付ける。呼び出し元（会話・他スキル）が渡す。下記「監査モードのトリアージ」で使う
- 対象文書の冒頭メタ情報から種別宣言（例:
- 種別: 設計書）を読む
- 宣言が無ければ内容から種別を推定して監査観点の冒頭で宣言し、「種別明記なし」を minor の指摘としてレポートに含める
- 任意で決定台帳（議論の決定・棄却・保留を記録したファイル。/workflow-design-notes が運用する
docs/DESIGN_NOTES.md 等）を受け取る。渡された場合のみ観点 6 を起動する
機械ゲートの直接実行（種別 = 設計書のとき）
サブエージェント起動の前に親が直接、doc-formats/design-doc.md の「機械ゲート」節の判定コマンド（POC_NEEDED blocker=true 残存）を実行し、違反を major としてレポートに含める。決定的な rg 判定を LLM に委ねない。この機械ゲートは監査モードに関わらず常時実行する（安価かつ決定的なため絞らない）。
監査モードのトリアージ（サブエージェント起動の前段）
観点別サブエージェントを全起動する「フル監査」と、変更に関係する観点だけに絞る「スコープ監査」を、文脈の有無で切り替える。局所修正の後に文脈を無視して文書全体をフル監査すると、変更と無関係な指摘までノイズとして返ってしまうため。
-
文脈の解決順
- 観点の絞り込み引数（例: 「用語閉包だけ」）があればそれを最優先で使う（従来どおり）
- なければ、入力で受け取った変更文脈引数を使う
- どちらも無ければ、親が対象ファイルの git diff を読む（unstaged + staged。無ければ
git log -1 があることを確認した上で HEAD~1..HEAD）。diff から変更点が特定できればそれを文脈とする
- 変更文脈引数も git diff も得られない（新規文書・削除されたファイル・「全体を監査して」等）場合はフル監査（従来どおり観点 1〜5 を常時起動）
-
フル監査への格上げ条件: 文脈が得られていても、変更が概念の追加・削除・置換・節構成の変更を含む場合はスコープ監査にせずフル監査する（rules/core/documentation.md の「全体整合 > 差分最小」と矛盾させないため）。台帳からの全文再生成（/workflow-design-notes 経由）も同様にフル監査を使う
-
スコープ監査時の観点トリアージ表（変更の性質から起動する観点を選ぶ）
| 変更の性質 | 起動観点 |
|---|
| 固有名（コマンド・用語・ファイル・節参照）の追加・リネーム | 1 用語・参照閉包 |
| データ・処理フローの記述変更 | 2 データフロー端到端 |
| 手順・セットアップ・運用記述の変更 | 3 運用・実装者視点 |
| 環境事実への言及（設定ファイル・CI・コマンド）の変更 | 4 依拠事実の突合 |
| メタ情報・節構成・表構造の変更 | 5 フォーマット適合 |
| 字句修正のみ（typo・表記揺れ） | 観点なし。「監査対象観点なし」とレポートして終了 |
複数の性質にまたがる変更は該当する観点をすべて起動する。決定台帳が渡されている場合、観点 6（決定カバレッジ）はモードに関わらず常時起動する。
-
トリアージ結果をレポート冒頭に 1 行宣言する（例: モード: スコープ監査 / 起動観点: 1,4 / 根拠: 新コマンド追加 + 設定パス変更）。誤判定にユーザが気付ける状態にする
観点別サブエージェントの並列起動
観点ごとにサブエージェントを model: opus 明示で同一ターンで並列起動する（文書監査は検証器なので実行器より下げない。rules/core/orchestration.md の検証器・調査 fan-out の割当に従う）。各エージェントには対象ファイルパス・下記の観点定義・キャリブレーション例・出力形式を渡し、「作業結果は必ず SendMessage で親に送ること」を指示文に含める。
スコープ監査時は、各エージェントの指示文に変更箇所（git diff の該当 hunk、または変更文脈引数の該当部分）を追加で含め、次を指示する: 「文書は全文 Read して検査する（読む範囲は狭めない）。指摘は変更にトレースできるものを主とし、変更にトレースできない既存の問題は『スコープ外』として分離報告する」。渡す変更箇所は書き手が編纂した抜粋ではなく git diff（客観情報）を使い、fresh context 監査としての独立性を保つ。検査対象文書自体の読解は従来どおりエージェント自身の全文 Read で行う。
観点（1〜5 は常時、6 は決定台帳が渡されたときのみ。実際に起動するかはモードのトリアージに従う）
- 用語・参照閉包: すべての固有名（コマンド・環境変数・ファイル・ラベル・フィールド・節参照）が定義され、定義と参照が一致し、表記揺れがないか
- データフロー端到端: 生成されるが消費されないデータ / 消費されるが生成元がないデータ / 記載データだけでは計算不能な指標・KPI / 経路の断絶
- 運用・実装者視点: 実装者・運用者が最初に詰まる問い（セットアップ・権限・障害時・ライフサイクル・Done 条件の判定可能性）に文書が答えているか
- 依拠事実の突合: 文書の「依拠する外部事実」節を実環境と rg で照合する。節が無ければその指摘 + 文書中の環境言及（設定ファイルの有無・コマンド・CI 等）を直接検証する
- フォーマット適合: 種別に対応する
rules/core/references/doc-formats/<型>.md を Read して突合する。構造違反 = major/minor、可読性違反 = suggestion の 2 層で報告する。規範未定義の型は rules/core/documentation.md の汎用原則のみでチェックし「規範未定義」と報告する
- 決定カバレッジ（決定台帳が渡されたときのみ）: 台帳の全「決定」が文書に反映されているか / 「棄却」した案が文書に生き残っていないか / 文書にあって台帳にない決定（無断発明）がないか。台帳→文書の再生成は lossy になりうるため、この観点が生成の安全網になる
各エージェントに含めるキャリブレーション例（探すべき問題の実例）
- 未定義コマンドの参照（本文が使う
xxx-sync コマンドがどこにも定義・導入されていない）
- 存在理由が消えた設定値（旧設計の競合対策だった値に、改訂後「負荷分散のため」と弱い理由が後付けされて残存）
- write-only なデータ（収集すると書かれているが、どの処理も参照しないログ・メトリクス）
- 「後述」「別途定義」のまま宙に浮いた参照（後述先が存在しない）
出力形式（各エージェントに指定）
[severity] 該当箇所 (節名 or 行) / 問題の一文 / 修正案の一文
severity: major = 実装者が止まる / minor = 説明不足・表記揺れ / suggestion = 可読性
スコープ監査時は、変更にトレースできない指摘を上記フォーマットのまま別リストに分け、「スコープ外」であることを明示して返す。
集約とレポート
- 冒頭に監査モードの宣言行を置く（「監査モードのトリアージ」4. で決めたもの）
- 各エージェントの指摘を親が検証する（明らかな誤読・文書外の要求は落とす）
- 観点間で重複する指摘を統合する
- severity 順（major → minor → suggestion）に整列してレポートする
- 末尾に「スコープ外の既存問題」節を置く（スコープ監査時のみ。severity は付けず 1 行/件で簡潔に列挙する。拾って直すかは呼び出し元の判断）
- さらに末尾に「検査した固有名・観点の要約」を 1 行添える（例:
検査: 固有名 12 件 / 2 観点 (スコープ監査) / 種別=設計書 (宣言あり)）
境界（対象外）
- 文体（AI っぽさ・語調・推敲）は対象外。別レイヤの関心事であり、プロジェクト側に文体スキルがある場合はそちらを使う
- スキル・テンプレートが生成した文書は、テンプレート準拠をもってフォーマット適合とみなす（規範の主対象はスキルを使わず手書きされる文書）
- 修正はしない。指摘レポートのみ
関連
rules/core/documentation.md — ドキュメント作業ルールの正本（本スキルは「編集後の整合性パス」の実行体）rules/core/references/doc-formats/ — 型別構造規範（フォーマット適合観点の正本）
