Doc review fix loop
[[doc-review-fix]] を収束するまで繰り返し実行する自動レビュー修正ループ。各イテレーションでレビュー（白箱＋読み手サブエージェント）→ 自動修正を行い、要確認で残置するもの以外の critical/major の新規検出がゼロに収束するか上限回数に達するまでループする。修正で内容が変わるたび新しい目で再レビューする。Use when user says 'ドキュメントを収束までレビュー修正して', 'doc-review-fix-loop', '自動修正ループ', '収束するまでレビュー'。1回だけなら [[doc-review-fix]]、ドキュメント作成は [[clear-document-writing]]（その Step 6 がこのループ）。From its SKILL.md
npx -y skills add sogengineer/lucidoc --skill doc-review-fix-loopAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
12.9 KB, as published. Nobody here has run it
Instructions
[[doc-review-fix]] を繰り返し実行し、全指摘が CONVERGED になるまで自動ループする。1パスのレビュー・分類・修正は doc-review-fix 側が担う。本スキルは「収束するまで回す・進捗を見せる・最終レポートを出す」に責務を限定する。
判断基準は一貫して 「読み手が効率よく目的を達成できるか（ISO 9241-11 の有効性・効率に対応）」。
パラメータ
| 引数 | 説明 | デフォルト |
|---|---|---|
| 1 | 対象ファイル（レビューするドキュメントのパス） | 直近に作成した成果物。特定できない場合は推測せず、ユーザーに確認する |
| 2 | 最大イテレーション数（安全弁） | 3（収束しなければ打ち切り） |
| 3 | 読み手像「誰に・何を・何のために」 | ドキュメントから読み取る／推定 |
例: /doc-review-fix-loop docs/manual.md 5 → 最大5回。/doc-review-fix-loop docs/manual.md 3 "新人エンジニアに、環境構築を、自力で完了してもらう" → 読み手像も指定。/doc-review-fix-loop docs/manual.md → 既定の最大3回。
対象が短い文書（目安50行未満の README 等）では、最大イテレーション数を 1〜2 に下げてよい（着手前メッセージでその判断を一言添える）。
進捗の可視化（必須）
1イテレーションでサブエージェントを並列起動するため、数分 × 最大N回かかる。沈黙厳禁。ユーザー向けテキストで必ず出す:
- 着手前: 「doc-review-fix-loop 開始: <ファイル> を最大Nイテレーション（1イテレーションあたりレビュー用サブエージェント3〜4体を起動、数分×N が目安）」
- 各イテレーション開始時: 「Iter K/N 開始: doc-review-fix 実行中」
- 各イテレーション完了時: 「Iter K/N 完了: critical=x major=y minor=z, Status=CONVERGED/NOT_CONVERGED」
- 完了時: 最終レポート表
短文でよい。各イテレーションの詳細は doc-review-fix 側が出すので、ループはサマリだけ蓄積する（全レビュー全文は親コンテキストに溜めない）。
設計判断: Agent ラッパーを介さず Skill を直接呼ぶ
doc-review-fix を起動するのに general-purpose Agent でラップしない。ラッパーは文脈分離のためだけに存在するが、文脈分離は doc-review-fix が内部で並列起動するレビュー用サブエージェントで十分確保され、結果は結果ファイル経由で親に伝わる（本リポジトリでの試行では、ラップは起動オーバーヘッドを増やすだけで分離上の利点がなかった——実測に基づく本スキル群の運用判断であり、Claude Code の公式仕様に基づく主張ではない）。
そこで本スキルは main session から [[doc-review-fix]] を Skill ツールで直接呼ぶ。
フォールバック: スキル内からの Skill ツール呼び出しは公式仕様で保証が明記された挙動ではない。Skill ツールで呼べない・呼び出しが失敗する環境では、doc-review-fix の SKILL.md を Read し、その手順（Phase 1〜5）を main session で直接実行する。結果ファイルの出力先は同じパスを使えば、手順2以降は同一に動く。呼び出し失敗を黙って握りつぶして CONVERGED 扱いにしない（結果ファイルが無ければ手順2で NOT_CONVERGED になる）。
実行手順
イテレーション・カウンタ K は 1 から開始し、手順0〜5を1巡するごとに 1 巡＝1イテレーションとして数える。N は最大イテレーション数（パラメータ2、既定3）。手順5で「K < N かつ未収束なら K を +1 して手順0へ」「K = N で未収束なら打ち切り」と判定する（N回目を実行し終えてから打ち切る）。
結果ファイルパスはループ側が1つ決めて全手順で共有する（既定はセッション固有の一時ディレクトリ（scratchpad 等）の doc-review-fix-result-<対象ファイル名>.md。対象名を含めることで並行・連続実行時の混同を防ぐ。これを正本とし、手順0の削除・手順1の引数・手順2の検証・最終レポートの転記すべてで同じパスを使う）。手順0の削除は各イテレーション開始時のみ行うため、CONVERGED で抜けても打ち切っても、最後のイテレーションの結果ファイルは消えずに残り、最終レポートの転記元として使える。
0. 前回結果ファイルの削除
各イテレーション開始前に、前回の結果ファイルを削除する（残存による誤判定を防ぐ）。doc-review-fix と同じ結果ファイルパス（上で決めた正本のパス）を使う:
rm -f <結果ファイルパス>
1. doc-review-fix の呼び出し
Skill ツールで [[doc-review-fix]] を呼ぶ（対象ファイル・読み手像・結果ファイルパスを引数で渡す）。doc-review-fix 内部で白箱1＋読み手N名のレビュアー・サブエージェントが並列起動し、レビュー・分類・自動修正・結果出力までを1パスで完遂する。
2. 結果ファイル検証
doc-review-fix 完了後、結果ファイルを Read で読む。ファイルが存在しない、または 対応サマリ テーブル・収束判定 セクションを含まない場合は、正しく実行されなかったとみなし NOT_CONVERGED とする。
3. 収束判定
結果ファイルの 対応サマリ テーブルと 収束判定 を見て、このイテレーションの判定ラベルだけを決める。ここでは終了・分岐しない——終了するかどうかは手順4（サマリ蓄積）を必ず済ませてから手順5で判断する。収束していてもこのイテレーションの行を最終レポート表に残すため、この順序を厳守する。
判定は一貫して 「このパスが新たに検出した、要確認で残置されない critical/major の件数」 で行う。これを 非要確認検出数 = （critical+major の検出）−（critical+major の要確認で残置） と定義する（対応サマリの "検出" 列と "要確認で残置" 列から算出）。"修正済み" で残置 0 でも、検出された以上そのパスは指摘を出している＝デグレ確認のため次パスが要る。非要確認検出数が 0 になって初めて収束とする。"要確認で残置" は捏造リスクで自動修正できず残るもので、これは収束を妨げない（下表 行2）。
| 条件 | 判定ラベル |
|---|---|
| 非要確認検出数 = 0 かつ 要確認で残置も 0 | CONVERGED |
| 非要確認検出数 = 0 かつ 要確認で残置あり（捏造リスク） | CONVERGED（要確認を明記済みであること） |
| 非要確認検出数 ≥ 1（critical / major いずれか） | NOT_CONVERGED |
| ファイル不在・形式不正 | NOT_CONVERGED |
重要: doc-review-fix が CONVERGED と自己申告していても、非要確認検出数 ≥ 1 なら NOT_CONVERGED とする。修正を行った以上デグレの可能性があるため、収束は対応サマリの検出数で裏取りする。
4. サマリ蓄積
結果ファイルの 対応サマリ から critical / major / minor の検出数を読み取り、手順3の判定ラベルと組にして 1行サマリ（Iter K | critical | major | minor | 判定ラベル） として記録する。最終レポート表の1行はこれをそのまま使う。
打ち切り（手順5の K = N 分岐）に備え、最後のイテレーションの結果ファイルは削除せず残す（手順0の削除は次イテレーション開始時のみ）。打ち切り時はこの結果ファイル本文（主な修正 や各指摘）から、最終パスが検出した要確認以外の critical/major（自動修正は適用済みだが、収束前に打ち切ったためデグレ未検証）を拾って最終レポートに記す。最後の結果ファイルが不在・形式不正で打ち切った場合は、その代わりに「最終パスが正常な結果を出せなかった」旨を記す。
5. ループ継続 / 終了判断
手順4でこのイテレーションの行を記録し終えてから、ここで初めて終了するか継続するかを決める（終了は必ずこの手順に一元化する）:
- 手順3の判定ラベルが CONVERGED → ループを抜けて最終レポートへ。
- NOT_CONVERGED かつ
K < N→ K を +1 して手順 0 に戻り次イテレーションへ。 - NOT_CONVERGED かつ
K = N（最大に到達） → 打ち切り。収束しなかった経緯（最終パスが検出した要確認以外の critical/major。修正適用済み・未検証）を最終レポートに記して終える。
捏造リスク（要確認）だけが残って収束しないループは回さない——doc-review-fix がそれを収束扱い（CONVERGED）にするので、本ループは無限化しない。
最終レポート
# doc-review-fix-loop 結果: <ファイル>
| Iter | critical | major | minor | 結果 |
| ---- | -------- | ----- | ----- | ------------- |
| 1 | 2 | 3 | 4 | NOT_CONVERGED |
| 2 | 1 | 0 | 1 | NOT_CONVERGED |
| 3 | 0 | 0 | 0 | CONVERGED |
**最終結果: CONVERGED**（または NOT_CONVERGED: 最大Nイテレーションで打ち切り）
## 収束しなかった経緯（NOT_CONVERGED で打ち切った場合のみ）
- 最終パス(Iter N)が検出した要確認以外の critical X件 / major Y件（自動修正は適用済みだが、収束前に打ち切ったためデグレ未検証）。観点・箇所・内容は最終イテレーションの結果ファイル本文から転記。
- 結果ファイルが不在・形式不正だった場合は「最終パスが正常な結果を出せなかった」旨を記す。
## 要確認で残した不足（あれば）
- <何が足りないか / 誰に確認すべきか>
Iter 表の各行は手順4で記録した1行サマリ（件数＋判定ラベル）をそのまま並べる。「収束しなかった経緯」節は CONVERGED で終えた場合は省略してよい。表の minor 列は記録・表示するが収束判定には用いない（収束は非要確認の critical/major で決まる）ため、minor が残ったまま CONVERGED で終えるのは正常。ただし収束パスで minor の自動修正（本文変更）を行っていた場合、その修正は新しい目での再レビューを経ていない——最終レポートに「最終パスの minor 修正 n 件は再レビュー未実施」と1行明記する。
注意事項
- レビュー用サブエージェントは doc-review-fix の Phase 1 内で並列起動され、それぞれ独立コンテキストで動く。親（このループ）には doc-review-fix 本文と各イテレーションのサマリだけが蓄積される。
- 修正適用（Phase 3）は doc-review-fix が main session で行うため、ユーザーは進行を直接観察できる。
- 振動の検出: 同一箇所に相反する方向の指摘が2イテレーション連続で出た場合（例: 否定形の肯定形化 ↔ 元のニュアンスへの復元）、3回目の自動修正はせず「要確認」に倒してユーザー判断に委ねる（レビュアー同士の好みの往復でイテレーションを浪費しない）。
- サブエージェントを dispatch できない環境では、doc-review-fix が白箱＋劣化版自己レビューに縮退する（その旨が結果ファイルに明記される）。ループはそのまま回せる。
- このループ全体が [[clear-document-writing]] の Step 6 の実体。作成（Step 1〜5）の直後に呼ぶことで、作成からレビュー修正までが一貫する。