| name | quick-doc-review |
| description | ドキュメント編集直後の軽量レビュー。よく指摘される項目だけを高速にチェックし、その場で修正する。「quick-doc-review」「軽くdocチェックして」と指示されたとき。大掛かりなレビューは /doc-review。 |
| argument-hint | [file-path] |
Quick Doc Review
/doc-review は文書の目的・対象読者・可視化提案まで含めた質的なレビューで、subagentを起動するため時間がかかる。本スキルはそれとは別物で、判断ログ上で繰り返し指摘されてきた具体項目だけを、メインの会話内で直接・高速にチェックし、その場で修正する。網羅的な品質判定はしない。
quick-issue と同様に「本格フローの軽量版」シリーズの1つ。
[!NOTE]
（AI・必須） 判定基準は本来 documentation-policy.md が正（SSOT）だが、本スキルは速度を優先し、そこから具体的な判定基準を書き下して自己完結させている（DRYより速度を優先した意図的な例外）。documentation-policy.md 自体が改訂されたときは、このチェック項目も追従して見直すこと。
対象
- 対象ファイル：引数にファイルパスがあればそれを対象にする。無ければ、直前のターンで自分がEdit/Writeしたファイルを対象にする。
- チェック範囲：
git diff HEAD -- <対象ファイル> で差分を取得する。差分があれば差分部分だけをチェック対象にする（速度優先のデフォルト）。差分が無ければ（コミット済みで変更がない、または新規追加ファイルで差分が出ない等）、ファイル全文を対象にする。
チェック項目・判定基準
| # | 項目 | 判定基準 |
|---|
| 1 | TL;DRが3行以内か | 文書冒頭に TL;DR／「決定事項」の要約ブロックがある場合、本文（見出し行を除く）が4行以上あればNG。決定を含まない事実列挙の文書（用語集・API一覧等）はTL;DR自体が無くてよく、対象外 |
| 2 | 経過・状態の記述がないか | 本文中に「整備中」「整備途上」「今後」「暫定」「TODO」「予定」「これから」等、進行中・未来のステータスを表す語が直書きされていればNG（人間の明示指示がある場合を除く）。未完了作業はIssue番号の参照に置き換える。対象は語だけでなく、色分け・バッジ・ハイライトなど**「今回追加した箇所」を示す視覚表現**も含む |
| 3 | 件数・列挙を転記していないか | 「◯つの」「N個の」等の個数表現が、直後ではなく離れた場所・別文書にある列挙を指しているとき、その個数や列挙内容をハードコードしていればNG。個数を書かず、参照（リンクや呼称）に置き換える |
| 4 | 文書内DRYが崩れていないか | 同一ファイル内で同じ主張・説明がほぼ同じ文言で2箇所以上繰り返されていればNG（calloutが直前の本文を再掲するケースを含む）。ただし特に重要なポイントを強調のためあえて繰り返すのは意図的な例外として許容する（例：冒頭TL;DRと末尾まとめでの要点再掲）。判断基準は「見落とし防止のための強調か、単なる書き忘れ的な重複か」 |
| 5 | 可視化すべき箇所が文章のまま埋もれていないか | 次のいずれかが表・図にならず文章のままならNG：①2項目以上の対比・分類（表にする。2項目でも該当）②複数要素が関係し合う説明（関係図）③複数の主体が時間順にやり取りする流れ（シーケンス図）④階層構造（ツリー図）⑤状態遷移（状態遷移図）⑥上のどれにも当てはまらない分岐・合流（フローチャート）。図種の選び直しは次項で見る。CLAUDE.md だけは例外で、①の表化は求めない（常時ロードされ、罫線のトークンを毎回払うため箇条書きでよい） |
| 6 | 図が過剰・図種が不適切でないか | 差分に図があるとき、逆変換テストを当てる：その図を表・箇条書きに戻して、文章を読まずに構造を掴めるならNG（戻す先を明示して指摘する）。図の価値は分岐・合流・ループ・並行・多対多・階層・状態遷移にあり、一直線（A→B→C）の箱並べは文章の言い換え。テキストへ復元できること自体は理由にならない（測るのは認知負荷）。加えて図種も見る：フローチャートは他のどの形にも当てはまらないときだけ選んでよく、シーケンス図・状態遷移図・ツリー図等が合う情報をフローチャートで描いていればNG。さらに、作図判断そのもの（「この表は図にしない」「この図種を選んだ理由」など）が本文に書かれていればNG——判断理由はユーザーへの回答に書くもので、読者の判断を何も変えない |
| 7 | 見出しに連番を振っていないか | ## 1. 目的 のような番号付き見出しがあればNG（番号なしに直す）。§3 [原則2](x.md) のように他文書の内部番号を名指しした参照もNG（見出し名・アンカーリンクに直す）。例外は実行順序そのものが情報である手順書（runbook・セットアップ手順・移行手順）。順序に意味がない列挙は手順書の中でもNG |
| 8 | calloutに宛先・強制力ラベルがあるか | 行動を促す callout（[!IMPORTANT] [!TIP] [!WARNING] 等）の本文が **（AI・必須）** のような宛先・強制力ラベルで始まっていなければNG。宛先は AI / 人間 / AI・人間、強制力は 必須（MUST） / 推奨（SHOULD）。両対象なら **（AI・必須 / 人間にも）**。行動を促さない補足・前提（[!NOTE] 等）はラベル不要で対象外 |
| 9 | 冗長な記述がないか | 各文・各行に削除テストを当てる：「この語句・行を消しても読者は判断に困らないか」を自問し、困らないほど具体的すぎる属性・修飾・繰り返しの説明があればNG。加えて「この内容を将来変更するとき、何箇所を直す必要があるか」も自問し、1箇所で済まないならハードコード・重複の兆候としてNG |
| 10 | 硬い言い回しになっていないか | 中学生テスト：専門用語を別の記号に置き換えたとき、残りの文の構造と論理を中学生が一度で追えるか。追えなければNG。音読テスト：声に出して言わない硬い言い回し（「〜を企図する」等）があればNG。専門用語そのものは数に入れない。直すのは言い回しと構造：漢語の硬い動詞を和語に（「担保する」→「保つ」）、名詞化をほどく（「変更への耐性を担保する」→「変更に強くする」）、一文の主語・述語は1組まで |
| 11 | 他文書リンクが必要最低限か | 他文書リンクを1本ずつリンク削除テストにかける：「消しても読者はこの文書だけで判断・行動できるか」。できなければNG（結論を1〜2文で転記してから、必要ならリンクを残す）。加えて次もNG：①同一リンク先を1文書で2回以上張っている ②「詳細はXを参照」だけで結論を本文に書いていない（リンク先の内部番号を名指しした参照は「見出しに連番を振っていないか」で見る）。ハブ文書（design-hub / policy-hub）と docs/reference/ の索引は対象外 |
チェック項目に載せない規約と理由
documentation-policy.md の規約のうち、次は意図的にチェック項目から外している。軽量チェックが成立する条件は「差分だけを見て、その場で直せる」ことで、これを満たさない規約は /doc-review の責務に置く。
| 載せない規約 | 理由 |
|---|
| 600行の分割目安 | 文書全体の構成判断であり、直し方が「その場で修正」ではなく分割提案になる |
| 500行超の目次必須 | 判定に要るのは行数と ## 目次 の有無だけで、差分を読む必要がない。/doc-review が全文を見るときに判定する |
| 対象読者・目的の明示と妥当性 | 文書の狙いを読み解く質的判断で、差分だけでは判定できない |
| 見出し・トピックセンテンスの質 | 同上。良し悪しに幅があり、機械的な判定基準に落ちない |
| 文書間DRY（SSOT） | 判定には差分の外の全文検索が要る。検索せずに「他文書に無い」と断定できてしまい、通らないゲートになる。/doc-consistency が見る |
チェック項目外の所見の扱い
対象を読む過程で、上記の全項目に当てはまらない問題に気づくことがある。その場合は確信度で扱いを分ける。
| 確信度 | 対応 |
|---|
| 明らかな問題（誤字・矛盾・壊れたリンク等、根拠を示せるもの） | その場で修正する |
| 怪しい・疑わしい程度（判断が分かれうる、根拠が弱い） | 修正せず、報告のみ行う |
出力と修正
- 対象を読み、上記の全項目をチェックし、次の表で報告する（OKの項目も含め全項目を報告し、見落としを隠さない）。チェック項目外の所見があれば表の下に追記する。
- NGがあれば、確認を挟まずその場でEdit/Writeを実行して修正する。修正内容は上表の該当行にコメントとして併記する。
- 修正が文書の構成そのものに関わる大きな変更（節の新設・削除など）になる場合は、実行前に一言その旨を添えてから進める。
