Doc review fix

Instructions

ドキュメント1本を レビュー → 診断・分類 → 自動修正 → 自己検証 → レポート出力 まで1パスで完遂する。レビューは独立したサブエージェントに実行させ、書いた本人には見えない曖昧さ・抜け漏れを外の目で拾う。

判断基準は一貫して 「読み手が効率よく目的を達成できるか（ISO 9241-11 の有効性・効率に対応）」。「きれいに書けたか」では評価しない。

このスキルは1パス（1イテレーション）で完結する。修正で内容が変われば再レビューが要るが、その収束ループは回さない——収束まで繰り返すのは [[doc-review-fix-loop]] の役割。本スキルは「1回ぶんのレビューと修正」に責務を限定する。

入力

入力	説明	取得方法
対象ファイル	レビューするドキュメントのパス	引数 or 直近に作成した成果物。特定できない場合は推測せず、ユーザーに確認する
読み手像	「誰に・何を・何のために」（[[clear-document-writing]] Step 1 の成果物）	引数 or ドキュメント冒頭から読み取る。不明なら本文から推定し「推定」と明記
元資料の所在	文書の出典（コードのパス・議事録・仕様の原典）。あれば C. 事実照合レビューが必須になる	引数 or ドキュメント冒頭・本文のリンクから読み取る。無ければ C は省略
結果ファイルパス	対応サマリ・収束判定の出力先	引数。既定はセッション固有の一時ディレクトリ（scratchpad 等）の doc-review-fix-result-<対象ファイル名>.md（対象名を含めて並行・連続実行の混同を防ぐ。[[doc-review-fix-loop]] がここを読む）

読み手像が取れないと黒箱レビューが成立しない。引数で渡されない場合は、ドキュメントの冒頭・タイトル・frontmatter から読み取り、取れなければ本文から最も妥当な読み手を推定して「読み手像（推定）」と明記する。

進捗の可視化（必須）

サブエージェントを並列起動するため数分かかる。沈黙しない。ユーザー向けに最低限を出す:

1. 着手時: 「doc-review-fix 開始: <ファイル名> をレビュー（白箱1 + 読み手N）」
2. レビュー完了時: 「レビュー完了: critical=x major=y minor=z」
3. 修正完了時: 「修正適用: 自動修正 a 件 / 情報補充 b 件 / 要確認 c 件」
4. 完了時: 対応サマリ表と収束判定

---

Phase 1: レビュー（サブエージェントを並列 dispatch）

レビュアーを並列に起動する（A・B は常時、C は元資料があるとき必須）。各サブエージェントは独立コンテキストで対象ファイルを Read し、所定のフォーマットで指摘を返す。観点が違うので該当する系統をすべてかける。

系統	何を見るか	人数
A. 白箱（ルーブリック採点）	このスキル群の原則を満たしているか（構造・見出し・中心文・文・図表・引き算）。機械的に検出できる欠陥	1名
B. 黒箱（読み手レビュー）	読み手が初見で目的を達成できるか。実際に読ませないと分からない欠陥	2〜3名
C. 事実照合（元資料があるとき必須）	文書の事実主張（名前・値・条件・順序・図の分岐）が元資料と一致するか。A・B は「ドキュメント外を参照しない」ため、critical の筆頭「誤情報」を検出できるのは C だけ	1名

各指摘は次のフォーマットで返させる（集約・分類しやすくするため）:

- 観点: <ルーブリック#番号 または Q1-Q4>
  深刻度: critical | major | minor
  箇所: <見出し名・引用・おおよその位置>
  指摘: <何が問題か>
  提案: <どう直すか。情報が無くて直せないなら「要情報: <何が足りないか>」>

深刻度の定義（全レビュアー共通）:

深刻度	意味
critical	読み手が目的を達成できない／誤情報がある
major	達成はできるが効率を著しく損なう
minor	推敲レベル（読みやすさの改善余地）

A. 白箱レビュアーの prompt テンプレート

あなたはドキュメントの構成レビュアーです。以下のドキュメントを読み、下のルーブリック
各項目を「合格 / 要修正」で採点してください。要修正には深刻度（critical/major/minor）と
箇所・提案を、指定フォーマットで挙げてください。ドキュメント外の情報は参照しません。

## ドキュメント
（Read で対象ファイルを読む。パス: <対象ファイル>）

## 読み手像
<誰に・何を・何のために>

## ルーブリック
1. 目的の明示: 誰に・何のためかが冒頭から読み取れるか
2. 1読み手1目的: 複数の読み手が混在して焦点がぼけていないか
3. Why/What/How: How（操作）偏重で Why・What が欠落していないか
4. 流し読み成立: 見出しだけで全体のあらましが掴めるか
5. 見出しの具体性: 「詳細」「その他」「〜とは」止まりで主張のない見出しがないか
6. 中心文の位置: 各段落の先頭に結論（中心文）があるか／1段落1主張か
7. 文の明確さ: 「適宜」「なるべく」「等」、一文多義、回りくどい否定形がないか
8. 読み手視点: 仕組みの説明に終始せず、得るもの・すべき操作が書かれているか
9. 図表の活用: 複数アクターの流れを文章でだらだら書いていないか／逆に図の作りすぎがないか
10. 引き算: 読み手の目的に効かない情報が混ざっていないか
11. 形式: frontmatter・リンク・体裁が崩れていないか

## 出力フォーマット
（上記の指摘フォーマットで、要修正の項目だけ列挙）

B. 黒箱レビュアー（読み手）の prompt テンプレート

2〜3名を、それぞれ独立に起動する。Q1 の正答（読み手像）へのアンカリングを避けるため、Q1 は読み手像の開示より前に置き、本文のみから答えさせる。Q1 と読み手像の一致判定はレビュアー自身ではなく、回答を集約する main session が行う（不一致は critical）。

以下のドキュメントを初見で読むレビューです。上から順に回答してください。
ドキュメントの外にある情報は参照せず、書かれていることだけから判断してください。

## ドキュメント
（Read で対象ファイルを読む。パス: <対象ファイル>）

## Step A（ドキュメント本文のみから回答。下の「読み手プロフィール」はまだ参照しない）
Q1: このドキュメントは誰の・何のためのものだと読み取れたか？

## 読み手プロフィール（Step B で使う）
あなたは次の読み手です:「<読み手像>」。

## Step B（読み手プロフィールの立場で回答。各1-2文）
Q2: 読み終えて、あなた（読み手）は目的を達成できるか？できないなら何が足りないか？
Q3: 曖昧・多義的で、解釈が割れた箇所はどこか？
Q4: 読み飛ばしても支障ない（不要な）情報はあったか？

## 回答後、気づいた問題を指定フォーマットで挙げてください
（Q2 未達は critical、Q3 は major〜minor、Q4 は minor。Q1 の一致判定は集約側が行うので、Q1 は回答のみでよい）

一部のレビュアーが失敗した場合

並列レビュアーの一部が失敗・タイムアウト・フォーマット不正で有効回答を返さなかった場合:

• 黒箱の有効回答が2名未満なら1回だけ再 dispatch する。
• それでも2名に満たなければ続行してよいが、レポートの「レビュー構成」に「黒箱: M（当初N名中、失敗により縮退）」と明記する。
• 収束判定の「読み手レビュー全員」は有効回答者を母数とする（母数が1名に縮退した場合はその旨も明記する）。

サブエージェントを dispatch できない場合

書き手自身がすでにサブエージェントとして動いている等で独立サブエージェントを起動できない環境では、Phase 1 を縮退実行する:

• A（白箱）は必ず自分で実施。ルーブリック採点は dispatch 不要。
• B（黒箱）は劣化版: 自分が読み手になりきり、時間を空けて初見のつもりで Q1〜Q4 に答える。客観視しにくく信頼度が下がるため、「読み手レビューは劣化版（自己レビュー）で実施」とレポートに明記する。
• NG: レビューを黙って飛ばすこと。飛ばすなら「レビュー未実施: dispatch 不可」と明示し、未検証を成果物の前提に残す。

---

Phase 2: 診断・分類（main session）

全レビュアーの指摘を集約し、重複（同じ箇所・同じ趣旨）をまとめる。各指摘を扱いの違う3分類に仕分ける。ここがハーネスの中核——「直せるものは自動で直し、直せないものは捏造せず印を残す」を機械的に判定する。

分類	条件	対応
自動修正	本文の書き換え・並べ替え・図表化・削除だけで直る（観点 4〜11 の多く、Q3・Q4）	Phase 3 でその場で直す
情報補充	critical だが、不足情報が元資料・文脈・既存資料に存在する	Phase 3 で該当情報を本文に補う
捏造リスク	critical だが、不足情報が元資料のどこにも存在しない	創作で埋めない。本文に「未確認／要確認」と明記し、何が欠けているかをレポートに残す

「存在する情報」の線引き（情報補充 ↔ 捏造リスクの判定で迷ったら、これで分ける）:

• 情報補充にしてよい: 不足情報が、元資料・与えられた文脈・既存資料に 明示的に存在する 場合のみ。対象 doc の他セクションが既に述べている内容の言い換え・整理・移動も含む（新情報を持ち込まないため、これは実質「自動修正」として扱ってもよい）。
• 捏造リスク（本文に事実として書かない）: システム / インスタンス固有の事実・数値・コマンド・名称・パス・分数など、出典に無いもの。「一般にこうだろう」という尤もらしい値も創作に含む。
• 一般原則の Why: ドメインで普遍的に成り立つ背景（例:「メンテナンスモード＝書き込み停止」）は、固有の未確認値を主張しない範囲で補ってよい。ただし この doc 固有の挙動として断定しない。少しでも迷うなら情報補充にせず「要確認」に倒す。
• メタデータ / frontmatter: frontmatter が無いこと自体は最大でも minor（体裁）。owner・作成日・最終レビュー日など出典に無いメタ値は捏造リスク扱い——プレースホルダの名前や日付で埋めない（特に「今日の日付」を created / last_reviewed に打たない）。足場として frontmatter を足すのは任意（clean な doc では足さなくてよい）。足す場合、不明なフィールドは値を 要確認 とする（空欄・省略でなく、はっきり要確認と書く）。
• doc 内の矛盾: doc 自身が食い違い（A 節と B 節で記述が矛盾する）、どちらが正しいかを出典で確定できない場合、片方に断定して揃えない——断定は捏造に当たる。捏造リスクとして両論を残したまま「要確認」を明記し、収束判定上は要確認残置として扱う（これは CONVERGED を妨げない）。

捏造しないことが「Q2 全員 OK」に優先する。 読み手が「足りない」と言っても、無い情報を作って通すのは誤り。要確認の明示が正しい次の一手であり、書き手が想像で埋める話ではない。

---

Phase 3: 修正適用（main session）

「自動修正」「情報補充」に分類された指摘を、対象ファイルに適用する。どこを・どう直したかを必ず記録する（レポートと収束判定に使う）。「捏造リスク」は本文に「要確認」と明記し、修正カウントには入れない。

修正の当て方は [[clear-document-writing]] の各 Step に従う（見出し→ Step 3、段落構成→ Step 4、文・図表→ Step 5）。

---

Phase 4: 自己検証と収束判定

修正で内容を変えた場合、その修正がデグレ（新たな曖昧さ・矛盾）を生んでいないかを確認する。直した箇所と、その前後の整合だけを軽く見直せばよい（全面再レビューはループ側 [[doc-review-fix-loop]] の責務）。

収束判定は次で決める。件数はすべて修正後に未解決で残る数（残存ベース）——対応サマリの「検出 −（修正済み＋要確認で残置）」:

条件	判定
残る critical = 0 かつ 残る major = 0 かつ 読み手レビュー全員が「目的を達成できる」	CONVERGED
残る critical が「捏造リスク（要確認で残置）」のみ	CONVERGED（要確認を明記済みであること）
上記以外（critical/major が残る、または読み手に未達者）	NOT_CONVERGED

この判定は1パスの自己評価であり、修正後の全面再レビューは行っていない。[[doc-review-fix-loop]] 経由では、ループ側が対応サマリの検出数から収束を裏取りし、この自己申告を上書きする（検出があったパスは CONVERGED 申告でも次パスが回る）。単体実行で修正を行って CONVERGED になった場合は、レポートに「1パス判定・修正後の全面再検証は未実施（収束保証はループ側）」と付記する。

---

Phase 5: 結果レポートの出力

ユーザー向けに表示し、同じ内容を結果ファイルにも書き出す（[[doc-review-fix-loop]] がパースする）。最低限の体裁:

# doc-review-fix 結果: <ファイル名>

## 対応サマリ
| 深刻度   | 検出 | 修正済み | 要確認で残置 |
| -------- | ---- | -------- | ------------ |
| critical | 2    | 1        | 1            |
| major    | 3    | 3        | 0            |
| minor    | 4    | 4        | 0            |

## 主な修正
- <観点/箇所>: <どう直したか>
- ...

## 要確認で残した不足（捏造せず）
- <何が足りないか / 誰に確認すべきか>

## レビュー構成
- 白箱: 1（ルーブリック採点）/ 黒箱: N（読み手レビュー）※ dispatch 不可時は劣化版と明記

## 収束判定
CONVERGED | NOT_CONVERGED

結果ファイルには 対応サマリ テーブルと 収束判定 セクションを必ず含める（これが無いとループ側が NOT_CONVERGED 扱いにする）。

---

よくある失敗

失敗パターン	対策
白箱だけ／黒箱だけで済ます	A（ルール準拠）と B（読み手の実害）は観点が違う。両方かける
自分で読み返して OK とする	書いた本人は客観視できない。独立サブエージェントに読ませる
足りない情報を創作で埋めて Q2 を通す	捏造リスクは「要確認」と明記して残す。捏造はしない
修正したのにデグレ確認をしない	Phase 4 で直した箇所の整合を見直す
結果ファイルに対応サマリ・収束判定を書かない	ループ側がパースできず NOT_CONVERGED になる。必ず書く
1パスで収束まで回そうとする	収束ループは [[doc-review-fix-loop]] の責務。本スキルは1パスに限定
レビューを「きれいさ」で評価する	評価軸は「読み手が目的を達成できるか」（ISO 9241-11）