utility-doc-audit

name	utility-doc-audit
description	ドキュメント (設計書・仕様書・調査結果・README 等) の整合性・フォーマット適合を fresh context のサブエージェント fan-out で監査する。指摘のみ行い、修正はしない。「この設計書を監査して」「ドキュメントを監査して」「/utility-doc-audit docs/DESIGN.md」「文書の整合性をチェックして」などのリクエストで起動。

/utility-doc-audit

ドキュメントを書き手と別コンテキストの複数観点で監査し、指摘レポートを返す。書き手自身は「定義したつもり」バイアスで未定義用語・断絶した参照を検出できない。fresh context のサブエージェントに検査させることが本スキルの存在理由。

**修正はしない。指摘レポートのみ。**修正するかどうか・どう直すかは呼び出し元の判断。

入力

1. 引数で対象ファイルパスを受け取る（複数可）。任意で観点の絞り込み（例: 「用語閉包だけ」）を受け付ける
2. 任意で変更文脈（何をどう修正したかの概要・修正意図）を受け付ける。呼び出し元（会話・他スキル）が渡す。下記「監査モードのトリアージ」で使う
3. 対象文書の冒頭メタ情報から種別宣言（例: - 種別: 設計書）を読む
   • 宣言が無ければ内容から種別を推定して監査観点の冒頭で宣言し、「種別明記なし」を minor の指摘としてレポートに含める
4. 任意で決定台帳（議論の決定・棄却・保留を記録したファイル。/workflow-design-notes が運用する docs/DESIGN_NOTES.md 等）を受け取る。渡された場合のみ観点 6 を起動する

機械ゲートの直接実行（種別 = 設計書のとき）

サブエージェント起動の前に親が直接、doc-formats/design-doc.md の「機械ゲート」節の判定コマンド（POC_NEEDED blocker=true 残存）を実行し、違反を major としてレポートに含める。決定的な rg 判定を LLM に委ねない。この機械ゲートは監査モードに関わらず常時実行する（安価かつ決定的なため絞らない）。

監査モードのトリアージ（サブエージェント起動の前段）

観点別サブエージェントを全起動する「フル監査」と、変更に関係する観点だけに絞る「スコープ監査」を、文脈の有無で切り替える。局所修正の後に文脈を無視して文書全体をフル監査すると、変更と無関係な指摘までノイズとして返ってしまうため。

1. 文脈の解決順

   1. 観点の絞り込み引数（例: 「用語閉包だけ」）があればそれを最優先で使う（従来どおり）
   2. なければ、入力で受け取った変更文脈引数を使う
   3. どちらも無ければ、親が対象ファイルの git diff を読む（unstaged + staged。無ければ git log -1 があることを確認した上で HEAD~1..HEAD）。diff から変更点が特定できればそれを文脈とする
   4. 変更文脈引数も git diff も得られない（新規文書・削除されたファイル・「全体を監査して」等）場合はフル監査（従来どおり観点 1〜5 を常時起動）

2. フル監査への格上げ条件: 文脈が得られていても、変更が概念の追加・削除・置換・節構成の変更を含む場合はスコープ監査にせずフル監査する（rules/core/documentation.md の「全体整合 > 差分最小」と矛盾させないため）。台帳からの全文再生成（/workflow-design-notes 経由）も同様にフル監査を使う

3. スコープ監査時の観点トリアージ表（変更の性質から起動する観点を選ぶ）

   変更の性質	起動観点
   固有名（コマンド・用語・ファイル・節参照）の追加・リネーム	1 用語・参照閉包
   データ・処理フローの記述変更	2 データフロー端到端
   手順・セットアップ・運用記述の変更	3 運用・実装者視点
   環境事実への言及（設定ファイル・CI・コマンド）の変更	4 依拠事実の突合
   メタ情報・節構成・表構造の変更	5 フォーマット適合
   字句修正のみ（typo・表記揺れ）	観点なし。「監査対象観点なし」とレポートして終了

   複数の性質にまたがる変更は該当する観点をすべて起動する。決定台帳が渡されている場合、観点 6（決定カバレッジ）はモードに関わらず常時起動する。

4. トリアージ結果をレポート冒頭に 1 行宣言する（例: モード: スコープ監査 / 起動観点: 1,4 / 根拠: 新コマンド追加 + 設定パス変更）。誤判定にユーザが気付ける状態にする

観点別サブエージェントの並列起動

観点ごとにサブエージェントを model: opus 明示で同一ターンで並列起動する（文書監査は検証器なので実行器より下げない。rules/core/orchestration.md の検証器・調査 fan-out の割当に従う）。各エージェントには対象ファイルパス・下記の観点定義・キャリブレーション例・出力形式を渡し、「作業結果は必ず SendMessage で親に送ること」を指示文に含める。

スコープ監査時は、各エージェントの指示文に変更箇所（git diff の該当 hunk、または変更文脈引数の該当部分）を追加で含め、次を指示する: 「文書は全文 Read して検査する（読む範囲は狭めない）。指摘は変更にトレースできるものを主とし、変更にトレースできない既存の問題は『スコープ外』として分離報告する」。渡す変更箇所は書き手が編纂した抜粋ではなく git diff（客観情報）を使い、fresh context 監査としての独立性を保つ。検査対象文書自体の読解は従来どおりエージェント自身の全文 Read で行う。

観点（1〜5 は常時、6 は決定台帳が渡されたときのみ。実際に起動するかはモードのトリアージに従う）

1. 用語・参照閉包: すべての固有名（コマンド・環境変数・ファイル・ラベル・フィールド・節参照）が定義され、定義と参照が一致し、表記揺れがないか
2. データフロー端到端: 生成されるが消費されないデータ / 消費されるが生成元がないデータ / 記載データだけでは計算不能な指標・KPI / 経路の断絶
3. 運用・実装者視点: 実装者・運用者が最初に詰まる問い（セットアップ・権限・障害時・ライフサイクル・Done 条件の判定可能性）に文書が答えているか
4. 依拠事実の突合: 文書の「依拠する外部事実」節を実環境と rg で照合する。節が無ければその指摘 + 文書中の環境言及（設定ファイルの有無・コマンド・CI 等）を直接検証する
5. フォーマット適合: 種別に対応する rules/core/references/doc-formats/<型>.md を Read して突合する。構造違反 = major/minor、可読性違反 = suggestion の 2 層で報告する。規範未定義の型は rules/core/documentation.md の汎用原則のみでチェックし「規範未定義」と報告する
6. 決定カバレッジ（決定台帳が渡されたときのみ）: 台帳の全「決定」が文書に反映されているか / 「棄却」した案が文書に生き残っていないか / 文書にあって台帳にない決定（無断発明）がないか。台帳→文書の再生成は lossy になりうるため、この観点が生成の安全網になる

各エージェントに含めるキャリブレーション例（探すべき問題の実例）

• 未定義コマンドの参照（本文が使う xxx-sync コマンドがどこにも定義・導入されていない）
• 存在理由が消えた設定値（旧設計の競合対策だった値に、改訂後「負荷分散のため」と弱い理由が後付けされて残存）
• write-only なデータ（収集すると書かれているが、どの処理も参照しないログ・メトリクス）
• 「後述」「別途定義」のまま宙に浮いた参照（後述先が存在しない）

出力形式（各エージェントに指定）

[severity] 該当箇所 (節名 or 行) / 問題の一文 / 修正案の一文

severity: major = 実装者が止まる / minor = 説明不足・表記揺れ / suggestion = 可読性

スコープ監査時は、変更にトレースできない指摘を上記フォーマットのまま別リストに分け、「スコープ外」であることを明示して返す。

集約とレポート

1. 冒頭に監査モードの宣言行を置く（「監査モードのトリアージ」4. で決めたもの）
2. 各エージェントの指摘を親が検証する（明らかな誤読・文書外の要求は落とす）
3. 観点間で重複する指摘を統合する
4. severity 順（major → minor → suggestion）に整列してレポートする
5. 末尾に「スコープ外の既存問題」節を置く（スコープ監査時のみ。severity は付けず 1 行/件で簡潔に列挙する。拾って直すかは呼び出し元の判断）
6. さらに末尾に「検査した固有名・観点の要約」を 1 行添える（例: 検査: 固有名 12 件 / 2 観点 (スコープ監査) / 種別=設計書 (宣言あり)）

境界（対象外）

• 文体（AI っぽさ・語調・推敲）は対象外。別レイヤの関心事であり、プロジェクト側に文体スキルがある場合はそちらを使う
• スキル・テンプレートが生成した文書は、テンプレート準拠をもってフォーマット適合とみなす（規範の主対象はスキルを使わず手書きされる文書）
• 修正はしない。指摘レポートのみ

関連

• rules/core/documentation.md — ドキュメント作業ルールの正本（本スキルは「編集後の整合性パス」の実行体）
• rules/core/references/doc-formats/ — 型別構造規範（フォーマット適合観点の正本）