---
name: utility-doc-audit
description: ユーザー起動専用のドキュメント監査。設計書・仕様書・調査結果・README 等の整合性とフォーマット適合を fresh context のサブエージェント fan-out で検査し、指摘のみ返す (修正はしない)。起動経路は 2 つだけ: (1) ユーザーが /utility-doc-audit <path> を実行する、(2) /workflow-design-notes の落とし込みフェーズ。普段の作業で自発的に起動してはいけない。
---

# /utility-doc-audit

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

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

## 起動経路

- ユーザーが `/utility-doc-audit <path>` を実行したとき
- `/workflow-design-notes` の落とし込みフェーズ (step 5) から起動されたとき

この 2 つ以外では起動しない。とくにドキュメントを編集した直後や「監査して」と依頼された場合は、自分で起動せず `~/.claude/rules/core/documentation.md`「編集後の整合性パス」3. の依頼 1 行を出してユーザーに委ねる。

## 入力

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. **フル監査への格上げ条件**: 文脈が得られていても、変更が**概念の追加・削除・置換・節構成の変更**を含む場合はスコープ監査にせずフル監査する（`~/.claude/rules/core/documentation.md` の「全体整合 > 差分最小」と矛盾させないため）。台帳からの全文再生成（/workflow-design-notes 経由）も同様にフル監査を使う
3. **スコープ監査時の観点トリアージ表**（変更の性質から起動する観点を選ぶ）

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

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

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

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

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

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

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

1. **用語・参照閉包**: すべての固有名（コマンド・環境変数・ファイル・ラベル・フィールド・節参照）が定義され、定義と参照が一致し、表記揺れがないか
2. **データフロー端到端**: 生成されるが消費されないデータ / 消費されるが生成元がないデータ / 記載データだけでは計算不能な指標・KPI / 経路の断絶
3. **運用・実装者視点**: 実装者・運用者が最初に詰まる問い（セットアップ・権限・障害時・ライフサイクル・Done 条件の判定可能性）に文書が答えているか
4. **依拠事実の突合**: 文書の「依拠する外部事実」節を実環境と rg で照合する。節が無ければその指摘 + 文書中の環境言及（設定ファイルの有無・コマンド・CI 等）を直接検証する
5. **フォーマット適合**: 種別に対応する `~/.claude/rules/core/references/doc-formats/<型>.md` を Read して突合する。構造違反 = major/minor、可読性違反 = suggestion の 2 層で報告する。規範未定義の型は `~/.claude/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 っぽさ・語調・推敲）は対象外**。別レイヤの関心事であり、プロジェクト側に文体スキルがある場合はそちらを使う
- **スキル・テンプレートが生成した文書**は、テンプレート準拠をもってフォーマット適合とみなす（規範の主対象はスキルを使わず手書きされる文書）
- **修正はしない**。指摘レポートのみ

## 関連

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