reviewable-design-doc

役割

設計資料としてレビューできる構造を作り、最終HTML生成は visual-html-renderer に渡す。

レビュー完了後は annotations/comments.json を読み、明確な指摘は設計へ反映し、確認・回答が必要な指摘は add-reply CLI でHTMLの同じコメントスレッドへ書き戻す（チャットへの回答ではなくHTML上の返信として）。

Role

Create a design document that can be reviewed in the browser. This skill owns design structure, review intent, comment ingestion, and comment-thread replies. Final HTML rendering is delegated to visual-html-renderer. After review, read annotations/comments.json, apply clear resolved feedback, and write clarification replies back into the same HTML comment thread with add-reply.

言語方針 / Language behavior

Follow the language of the latest user request for progress updates, final responses, and review handoff text. レビューコメントへの返信は、原則としてそのコメント本文の言語に合わせる。日本語コメントには日本語で、英語コメントには英語で返信する。設計本文や引用内容は、ユーザーが翻訳を求めない限り勝手に翻訳しない。

基本手順

1. 設計対象、読者、レビュー目的、完了条件を整理する。
2. 要求、制約、アーキテクチャ、代替案、意思決定、未決事項へ分解する。
3. レビュー観点とコメントしてほしい範囲を明示する。
4. 最初から document-model.json を作る。設計本文の下書きや中間成果物として .md を作らない。
5. 文書モデルには、要求、制約、アーキテクチャ、代替案、意思決定、未決事項、レビュー観点を、それぞれ現行rendererで有効なHTML表現を選んだblockとして入れる。
6. image.generation_status=requested のブロックがある場合は、imagegen skillで画像を生成し、attach-image CLIで文書モデルへ添付する。
7. check-model CLIで最終render前の文書モデル品質を検査する。
8. render CLIでHTML bundleを生成する。
9. validate CLIでHTML bundleを検証する。
10. ユーザー向け最終HTMLでは既定で preview CLIを --mode auto で起動し、返却JSONの url と stop_command を最終応答に必ず書く。
11. preview 起動直後に、Monitor ツールで watch-comments を開始する。これによりブラウザからのコメントを自動検知できるようになる。Monitor 起動コマンド: python3 -m scripts.html_review_workbench.cli watch-comments --root <output-dir>。イベント受信後の処理は「コメント自動回答と解決待ちゲート」セクションに従う。
12. ユーザーがコメントを入れたら「レビューコメントへの対応」セクションに従う。

Basic Workflow

1. Clarify the design target, audience, review purpose, and completion criteria.
2. Split the material into requirements, constraints, architecture, alternatives, decisions, unresolved issues, and review points.
3. Create document-model.json from the start; do not create a .md draft as the design body.
4. Choose renderer-supported HTML blocks for each design unit.
5. Generate requested images with imagegen and attach them before rendering.
6. Run check-model, render, validate, and preview.
7. Start watch-comments after preview startup.
8. When the user adds comments, ingest them, reply in the HTML thread to every thread listed in needs_agent_review_threads, and apply resolved feedback only after gates allow it.

設計資料モデル作成の規約

設計資料作成は、.md 原稿をHTMLへ変換する作業ではない。reviewable-design-doc は、設計内容を最初からレビュー可能なHTML bundleの情報設計として作る。

• 新規に設計資料を作る場合、最初の保存対象は output/tmp/<purpose>/document-model.json または output/<YYYY-MM-DD>_<name>/document-model.json にする。
• .md ファイルを設計本文の下書き、中間成果物、HTML化対象として作らない。
• 一時的に自然文入力を保存する必要がある場合だけ、source.txt, input.txt, source-content.txt のようなプレーンテキスト名を使う。

• 設計資料の本文は、見出し記号を含む原稿ではなく、blocks[].title, blocks[].type, blocks[].heading_level, blocks[].content, review_required を持つ文書モデルとして表現する。
• 大区分のブロック（背景・要求、アーキテクチャ、代替案比較、意思決定、未決事項など）には heading_level: 2 を設定し、その配下の詳細ブロックには heading_level: 3 を使う。各章の冒頭にはその章で扱う内容を示す導入段落を置く。
• title に章番号を書かない。番号は renderer が heading_level と blocks の並びから自動で振るため、"3. 代替案の比較" と書くと本文でも目次でも番号が二重になる。順序と階層は blocks の並びと heading_level で表す。
• 比較・代替案・評価軸は html block内の <table>、手順は <ol>、並列項目は <ul>、操作例・ログ・コマンドは <pre><code>、処理・依存・構成はdiagramブロック、決定・前提・注意はplain textのcallout、レビューしてほしい論点は専用のレビュー観点blockにする。
• section, text, table block typeは現行rendererに専用描画がないため、最終モデルでは使わない。
• diagramブロックはMermaid sourceを構造保存用に残し、生成画像を主表示にする。生成画像が未添付の場合、全diagram kindを同梱 mermaid.js でブラウザ描画し、standalone publishでは mermaid.js と図の拡大用scriptをHTMLへinline化する。Mermaid v11系の記法に準拠してsourceを書く。sourceに無い関係や判断を画像側で追加しない。
• Mermaidで描画される図は、図右上の拡大ボタンから全画面表示に切り替え、pan / zoom で詳細を確認できる。
• 既存資料を取り込む場合も、既存ファイルをそのまま表示へ流し込まず、visual-html-renderer のHTML情報設計規約に従って文書モデルへ再構成する。
• build-model は最終HTMLモデルを作るplannerではなく、入力退避用のsource-capture draftに限る。既存本文やユーザー指定内容を取り込む場合も、そのdraftをそのままrenderせず、agentが設計構造を判断して文書モデルを直接作る。

html block で使える表現部品

同梱の style.css には、html block 内でそのまま使える表現 class が実装済みである。比較・評価・推奨・決定がある内容では、素の <table> / <p> で終えず、該当する部品を選ぶ。

用途	class	書き方
表番号 + 表題	table-wrap / table-cap / t-no / t-title / table-scroll	<figure class="table-wrap"><figcaption class="table-cap"><span class="t-no">表 1</span><span class="t-title">3 案の比較</span></figcaption><div class="table-scroll"><table>…</table></div></figure>
表ヘッダの補助説明	axis-sub	<th scope="col">実装量<span class="axis-sub">行数の目安</span></th>
5 段階評価	rate + good/mid/low + r1〜r5 + pips / pip	<span class="rate good r4"><span class="pips"><i class="pip"></i><i class="pip"></i><i class="pip"></i><i class="pip"></i><i class="pip"></i></span>容易</span> (pip は常に 5 個。rN が塗る数、good/mid/low が色)
可否・対応状況	tag-yes / tag-no / tag-cell-note	<td><span class="tag-yes">対応</span><span class="tag-cell-note">v2.0 以降</span></td>
桁揃え数値	num	<td><span class="num">1,024</span></td> (表中の数値列に使う)
推奨パネル	reco / reco-tag	<div class="reco"><span class="reco-tag">推奨</span><p>案 B を採る。理由は…</p></div>
決定の枠囲み	decision-panel	<div class="decision-panel"><p>…</p></div>
コード内の着色 (新規は language-* 既定)	language-* (自動) / 互換の tok-k / tok-f / tok-s / tok-c / tok-n	新規: <pre><code class="language-python">def main():</code></pre>。手動着色 (互換): <pre><code><span class="tok-k">def</span> …</code></pre>。同梱 highlight.js が language-* を自動着色する。tok-* を含む code / pre.diff / .nohighlight は自動着色しない
コード差分	pre.diff + .add / .del / .ctx	<pre class="diff"><span class="ctx"> context</span><span class="del">removed</span><span class="add">added</span></pre>。変更理由を散文で説明してから、必要な断片だけ示す
用語集	dl.glossary	<dl class="glossary"><dt>用語</dt><dd>定義</dd></dl>。文書冒頭の html block に置く。専門用語は本文で使う前に 1〜2 文で定義し、前提用語が多い文書は用語集を置く

多軸の比較表 (table.cmp)

軸が 3 つ以上ある比較、または行数が多くて横スクロールが要る比較には <table class="cmp"> を使う。通常の <table> と違い、ヘッダ行と最初の列 (比較軸) がスクロール中も固定され、推奨案の列を緑で浮かせられる。

class	効果
cmp (table に付ける)	比較表本体。thead th が sticky ヘッダになる。最小幅 720px のため table-scroll の中に入れる
axis (最初の列の th / td に付ける)	比較軸の列が横スクロール中も左端に残る
pick (<col> / th / td に付ける)	推奨する案の列を緑系で強調する。<colgroup><col><col class="pick"></colgroup> で列単位、または個別セルに付ける

<figure class="table-wrap">
  <figcaption class="table-cap"><span class="t-no">表 1</span><span class="t-title">3 案の比較</span></figcaption>
  <div class="table-scroll">
    <table class="cmp">
      <colgroup><col><col><col class="pick"><col></colgroup>
      <thead><tr>
        <th scope="col" class="axis">評価軸</th>
        <th scope="col">案 A</th><th scope="col" class="pick">案 B</th><th scope="col">案 C</th>
      </tr></thead>
      <tbody>
        <tr><th scope="row" class="axis">実装量<span class="axis-sub">行数の目安</span></th>
            <td><span class="num">40</span></td><td class="pick"><span class="num">180</span></td><td><span class="num">920</span></td></tr>
      </tbody>
    </table>
  </div>
</figure>

軸が 2 つだけ、または行が少なく横スクロールが不要な表では、cmp を使わず素の <table> にする。sticky と最小幅は狭い表では邪魔になる。

使い分けの基準:

• 比較表には table-wrap + table-cap で番号と表題を付ける。本文からの参照は「表 1」で行う。
• 軸が 3 つ以上あるなら table.cmp + axis を使い、推奨案の列に pick を付ける。
• 評価軸 (容易さ・成熟度・リスク等) は文字だけでなく rate の点表示でも符号化する。
• 推奨・決定は本文の段落に埋めず、reco または decision-panel で独立させる。
• 段落を文字の大きさで強調しない。強調したい段落があるなら、それは推奨・決定・注意のいずれかなので、reco / decision-panel / callout block のうち内容に合うものを使う。文書全体の導入は metadata.deck が担うので、節ごとに導入段落を作らない。
• これらは class 指定だけで効く。style 属性の直書きで同等の見た目を再実装しない。
• 色は metadata.palette の brand / brand_soft だけ主題に合わせて上書きできる。コントラスト比は check-model / render / validate が WCAG 4.5:1 で検査し、不足すると error で止まる (brand は最も薄い地色との比、brand_soft は本文色との比、両方指定時は 2 色の相互比も見る)。

Style Classes Available in html Blocks

The bundled style.css ships ready-to-use presentation classes for html blocks. When the content contains comparisons, ratings, recommendations, or decisions, do not stop at bare <table> / <p>: use table-wrap + table-cap (numbered table captions), axis-sub (header sub-labels), rate good|mid|low r1..r5 with five pip elements (dot ratings), tag-yes / tag-no / tag-cell-note (availability cells), num (tabular figures), reco + reco-tag (recommendation panel), decision-panel (decision box), language-* on <pre><code> for automatic syntax highlighting via bundled highlight.js (default for new docs; keep tok-k / tok-f / tok-s / tok-c / tok-n only for compatibility with manually colored spans), pre.diff with .add / .del / .ctx for code diffs (explain the change in prose first, then show only the needed fragment), and dl.glossary for term definitions at the top of the document. Automatic highlighting skips pre.diff, .nohighlight, and any code that already has tok-* descendants. Reference numbered tables from body text as "表 1" / "Table 1". These work by class alone; do not re-implement the same look with inline style attributes. Do not emphasize a paragraph by making its type larger — if a paragraph deserves emphasis it is a recommendation, a decision, or a warning, so use reco, decision-panel, or a callout block instead. The document-level intro is metadata.deck; do not add a per-section intro paragraph.

For comparisons with three or more axes, use <table class="cmp"> inside table-scroll: the header row stays sticky while scrolling, axis on the first column keeps the comparison axis pinned during horizontal scroll, and pick on a <col>, th, or td tints the recommended option's column green. Keep plain <table> for narrow two-column comparisons — the sticky behavior and 720px minimum width get in the way there.

表現の質の指針

見た目の判断に迷った時は、次の 4 つに従う。ユーザーが見た目の方向を明示した場合は、その指定が常に優先する。

1. AI が作りがちな見た目を避ける。 次の定番の組み合わせは、指定が無い限り選ばない: cream 地 (#F4F1EA) + serif 見出し + terracotta accent / near-black 地 + acid-green や vermilion の一点差し / 絵文字を節の目印にする / 全要素センタリング / 一様な大きい角丸 / 角丸カードの左端 accent バー。
2. 構造装飾は内容の事実を符号化する。 01 / 02 / 03 のような番号は、内容が本当に順序を持つ時 (手順・時系列) だけ使う。区切り線・eyebrow・ラベルも、内容の区分を実際に表す時だけ入れ、装飾目的では入れない。
3. 読む文書と操作する画面で作法を変える。 一覧・ダッシュボード的な内容は上から順に読まれず走査される。要約を詳細より先に置き、状態は数値だけでなく形 (rate の点、tag-yes の色、callout の左帯) でも符号化して、注意が要る箇所が一目で分かるようにする。
4. 余白は layout で作る。 兄弟要素の間隔は gap を持つ flex / grid で作り、要素ごとの margin を積まない。幅の広い表・コード・図は自前の overflow-x: auto コンテナ (表は table-scroll) に入れ、ページ全体を横スクロールさせない。

図と手順の表現指針

• 原典図の引用優先。 原典に重要な図がある場合は出所を明示して引用し、模倣図を作らない。
• 矢印文字・絵文字を図記号にしない。 図が要るなら Mermaid diagram block か inline SVG を使う。
• 直列手順をフローチャート化しない。 単純な直列手順は番号付きリストで表現する。
• Mermaid の mindmap を使わない。 mindmap は日本語などの CJK ラベルで箱の採寸を誤り、文字が箱からはみ出し・重なって崩れる (2026-08-06 実測)。放射状の分類は flowchart の中心ノード + 枝で表現する。
• inline SVG の色は theme に追従させる。 紙面に直接乗る文字・線 (軸ラベル・行列の見出し・凡例の説明文・座標軸・区切り線) は fill="currentColor" / stroke="currentColor" で書き、#333 のような固定色を直書きしない。固定色は light theme でしか読めず、dark theme では紙面と同化して消える。塗りつぶした図形 (rect / path) 自体の色と、その塗りの上に重ねる文字は、両 theme で読める固定色でよい。

印刷と PDF

ブラウザの印刷ダイアログ (@media print) で topbar / toc / comment rail 等の操作 UI が消え、横スクロールしていた表・コードは折り返して全内容が残る。PDF 化が必要な時だけ python3 -m scripts.html_review_workbench.cli export-pdf --root <output-dir> [--output <pdf-path>] を実行する (headless Chrome 必須。不在時は error JSON)。preview URL の提示が既定であり、ユーザーが PDF を明示依頼した時だけ export-pdf する。

Design Quality Guidance

When unsure about visual choices, follow four rules; explicit user direction always wins. (1) Avoid stereotypical AI-generated looks — cream (#F4F1EA) with serif display and terracotta accent, near-black with a lone acid-green pop, emoji as section markers, centering everything, uniformly large border radii, accent bars on rounded cards. (2) Structural devices must encode facts: numbered markers (01/02/03) only when the content truly is a sequence; rules, eyebrows, and labels only when they mark real divisions. (3) Documents are read, dashboards are scanned: put summaries before detail and encode state in form (rating dots, tag colors, callout stripes), not numbers alone. (4) Create spacing with gap in flex/grid rather than stacked per-element margins, and give wide tables/code/diagrams their own overflow-x: auto container (table-scroll for tables) so the page body never scrolls sideways.

Diagram and procedure guidance: (a) Prefer citing an original figure with attribution over redrawing it. (b) Do not use arrow characters or emoji as diagram symbols — use a Mermaid diagram block or inline SVG when a figure is needed. (c) Do not turn a simple linear procedure into a flowchart; use a numbered list. (d) Do not use Mermaid mindmap: it mis-measures CJK labels so text overflows and overlaps its node boxes (observed 2026-08-06); express radial groupings as a flowchart with a central node and branches. (e) In inline SVG, draw text and strokes that sit directly on the page (axis labels, row/column headings, legend captions, rules) with fill="currentColor" / stroke="currentColor" instead of hard-coded colors such as #333, which are legible only in the light theme and disappear against the dark theme's paper; fills of shapes and the text placed on top of those fills may keep fixed colors as long as both themes can read them.

Print and PDF: browser print (@media print) hides chrome (topbar, toc, comment rail) and unwraps horizontal-scroll tables/code so content is preserved. Run export-pdf only when the user explicitly asks for a PDF (python3 -m scripts.html_review_workbench.cli export-pdf --root <output-dir>); preview URLs remain the default. Headless Chrome is required; missing Chrome returns an error JSON (no external service fallback).

操作部品 (触って試す / 触った結果を作業へ戻す)

読むだけでなく触って決める資料では、html block に操作部品を直接書ける。値を試すスライダー、切り替えのトグル、並べ替えできるカードなどが対象。

書ける範囲

• html block の中に <script> を inline で書ける。onclick= 等の inline event handler も使える。
• 外部 host からの読み込みは check-model が error にする (<script src="…"> と <link rel="stylesheet" href="https://…"> の両方)。bundle が手元で完結する性質を保つため。図表の描画ライブラリが要る場合は Mermaid の diagram block を使う。
• 部品の見た目は既存の class (rate / tag-yes / num 等) と揃える。inline style の直書きは最小限にする。

触った結果を保存する

同梱の RHWState を使う。preview server があれば PUT /annotations/state/<name>.json で保存し、端末をまたいで同じ状態を見せる。server が無い場合 (publish した standalone、file:// で開いた場合) は localStorage に落ち、どちらも使えない環境ではメモリ上だけで動く。操作そのものは止まらない。

<label>duration <input type="range" id="dur" min="0" max="2000" value="300"></label>
<output id="durOut">300</output>ms
<script>
  (async function () {
    var dur = document.getElementById("dur");
    var out = document.getElementById("durOut");
    // 保存済みの値があれば復元する
    var saved = await window.RHWState.load("tuning");
    if (saved && saved.duration) { dur.value = saved.duration; out.textContent = saved.duration; }
    dur.addEventListener("input", function () {
      out.textContent = dur.value;
      // 動かしている間の表示更新と一緒に呼んでよい。debounce が server への PUT をまとめる
      window.RHWState.save("tuning", { duration: dur.value }, { debounce: 300 });
    });
  })();
</script>

<name> は英数字とハイフン・アンダースコアだけ (最大 64 文字)。保存した内容は agent が annotations/state/<name>.json として読める。触って決めた結果を作業へ戻す経路がこれになる。文書の中で用途ごとに名前を分ける (tuning / priority-order など)。

連続して動く部品 (スライダー、テキスト入力) では { debounce: 300 } を渡す。手元の保存 (localStorage) は毎回すぐ行い、server への書き込みだけを入力が止まってから 1 回にまとめる。これを渡さずに input で呼ぶと、つまみを端から端まで動かすだけで PUT が 100 回以上飛ぶ。

逆に debounce を渡さないのは、操作が 1 回で完結する部品 (ボタン、dragend、チェックボックス) のとき。その場で保存され、戻り値の saved が remote / local / memory のどれかになる。

debounce 付きで待っている間の戻り値は superseded になる (新しい値で予約が取り直された、という意味)。最後の呼び出しだけが実際の保存結果を返す。画面に保存状態を出す場合は superseded を「保存中」として扱う。

使う判断

• 値の範囲を試したい、順序を決めたい、選択肢を絞りたい場面で使う。読んで終わる資料には入れない。
• 操作した結果を agent が受け取る必要があるなら RHWState.save() を必ず呼ぶ。呼ばないと結果は画面上だけで消える。
• 操作部品を入れた資料は、preview で server 越しに開いて動作を確認する。file:// で開くと状態が端末間で共有されない状態の確認になる。

Interactive Controls (Try Values, Return the Result to the Session)

For documents where the reader decides by manipulating rather than only reading, write controls directly into an html block: sliders for trying values, toggles, reorderable cards.

Inline <script> and inline event handlers are allowed inside html blocks. Loading from an external host is rejected by check-model — both <script src="…"> and <link rel="stylesheet" href="https://…"> — so the bundle stays self-contained. Use the diagram block when you need diagram rendering.

To persist what the reader manipulated, use the bundled RHWState. With a preview server it saves through PUT /annotations/state/<name>.json so state is shared across devices; without one (published standalone, opened via file://) it falls back to localStorage, and to memory when neither is available. The interaction never breaks.

<label>duration <input type="range" id="dur" min="0" max="2000" value="300"></label>
<output id="durOut">300</output>ms
<script>
  (async function () {
    var dur = document.getElementById("dur");
    var out = document.getElementById("durOut");
    var saved = await window.RHWState.load("tuning");
    if (saved && saved.duration) { dur.value = saved.duration; out.textContent = saved.duration; }
    dur.addEventListener("input", function () {
      out.textContent = dur.value;
      window.RHWState.save("tuning", { duration: dur.value }, { debounce: 300 });
    });
  })();
</script>

<name> accepts alphanumerics, hyphens, and underscores (64 chars max). Saved state is readable by the agent at annotations/state/<name>.json — that is the path by which a decision made in the browser returns to the session. Use distinct names per purpose (tuning, priority-order). For continuously moving controls (sliders, text inputs) pass { debounce: 300 }: local storage is written on every call, while the server write is coalesced into one after input stops. Omit debounce for one-shot interactions (buttons, dragend, checkboxes). While a debounced write is waiting, save() resolves with saved: "superseded" — treat that as "saving" in any status display; only the final call reports the real result.

Add controls only when the reader needs to try values, decide an order, or narrow options; leave them out of read-only documents. If the agent must receive the outcome, RHWState.save() is required — otherwise the result stays on screen and disappears. Verify interactive documents through preview over the server, since opening via file:// exercises the fallback path instead.

Mermaid 対応 kind と最小サンプル

diagramブロックのMermaid sourceは、mermaid.js v11系が対応する記法から選ぶ。同梱済み mermaid.min.js がHTML上でSVGに置換する。

主要 kind:

kind	用途
flowchart / graph	処理・依存関係のフロー
sequenceDiagram	相互作用・時系列メッセージ
stateDiagram-v2	状態遷移
classDiagram	クラス構造・継承・関連
erDiagram	エンティティ関係
gantt	期間・スケジュール
journey	ユーザー体験の順序
timeline	時系列イベント
mindmap	概念マップ・分類
pie	割合
gitGraph	ブランチ・マージ
requirementDiagram	要件・トレーサビリティ
quadrantChart	2軸マトリクス
sankey	フロー量
xychart-beta	2次元数値プロット
architecture-beta	システム構成
block-beta	ブロック配置
packet-beta	パケット構造
kanban	カンバンボード
radar	レーダーチャート
treemap	階層構造の面積表現
zenuml	ZenUML記法

最小サンプル:

erDiagram

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        string id PK
        string name
    }
    ORDER {
        string id PK
        string customer_id FK
    }

sequenceDiagram

sequenceDiagram
    participant User
    participant API
    User->>API: request
    API-->>User: response

stateDiagram-v2

stateDiagram-v2
    [*] --> Idle
    Idle --> Running: start
    Running --> Idle: stop

flowchart LR

flowchart LR
    A[Input] --> B{Decide}
    B -->|yes| C[Do it]
    B -->|no| D[Skip]

sourceの記法が不確かな場合は mermaid.js 公式docs (https://mermaid.js.org/) を参照する。schemaの diagram_kind は表示ラベル用のグループ名で、Mermaidの内部kind名と一致させる必要はない。

Mermaid Kinds and Minimal Samples

Use Mermaid source supported by mermaid.js v11. The bundled mermaid.min.js renders diagram blocks into SVG in the browser, and rendered Mermaid diagrams can be opened from the zoom button for full-screen pan / zoom inspection. Common kinds include flowchart / graph, sequenceDiagram, stateDiagram-v2, classDiagram, erDiagram, gantt, journey, timeline, mindmap, pie, gitGraph, requirementDiagram, quadrantChart, sankey, xychart-beta, architecture-beta, block-beta, packet-beta, kanban, radar, treemap, and zenuml. If syntax is uncertain, check the Mermaid docs. The schema diagram_kind is a display grouping label and does not need to match Mermaid's internal kind name.

Design Document Model Rules

This skill does not convert a .md draft into HTML. It designs a reviewable HTML bundle from the beginning. Store new models under output/tmp/<purpose>/document-model.json or output/<YYYY-MM-DD>_<name>/document-model.json. If temporary natural-language input must be saved, use plain text filenames such as source.txt, input.txt, or source-content.txt. Use heading_level: 2 for major sections and heading_level: 3 for detailed subsections. Never put chapter numbers in title: the renderer numbers headings automatically from heading_level and block order, so "3. Comparing alternatives" ends up doubled in both the body and the table of contents. Represent comparisons with tables, steps with ordered lists, parallel items with lists, commands and logs with code blocks, flows and dependencies with diagrams, and decisions or cautions with callouts.

レビューコメントへの対応

ユーザーが「コメント入れた」「レビューした」「ingest review comments」「process review comments」「reply to review comments」「apply resolved comments」等でコメントの存在を知らせた時に開始する。文書作成（手順 1-10）とは独立したインタラクションであり、以下を毎回実行する。

IMPORTANT: レビューコメントへの回答は、必ず add-reply CLI で HTML コメントスレッドに書き戻す。チャットだけで回答を返して終わりにしてはならない。チャットでは補足や次のアクション提案のみ行い、コメントへの実質的な回答は HTML 側に書く。

手順

1. ingest-review CLI でコメントを分類し、annotations/review-cycle-state.json に状態を保存する。ingest-review はコメントスレッドへ返信を書かない。
2. 分類結果に関係なく、各コメントの comment と selected_text を読み、設計資料の該当箇所の文脈を踏まえてコメントの意図を理解する。
3. 回答・受領・確認依頼が必要なコメントには、実質的な回答を add-reply CLI で HTML コメントスレッドに書き戻す。
4. actionable なコメントは、解決待ちゲートが開いてから設計へ反映し、必要に応じて再 render する。
5. ユーザーにブラウザでの確認を依頼する。

なぜチャット回答ではなく add-reply か

• ユーザーはブラウザ上でコメントと回答をセットで読む。チャットに書いた回答は、コメントの文脈から切り離される。
• 複数コメントがある場合、チャットでは各コメントへの回答の対応関係が崩れる。
• HTML 上の回答はコメントスレッドに紐づいて永続化される。チャットの回答はセッション終了で消える。

Handling Review Comments

Start this workflow when the user says comments were added or asks to ingest review comments, process review comments, reply to review comments, or apply resolved comments. Always run ingest-review to write review-cycle state only, inspect each comment's comment, selected_text and full replies, write substantive answers with add-reply for every thread in needs_agent_review_threads, and apply resolved feedback only when the review gates allow it. Do not answer only in chat; the durable answer belongs in the HTML comment thread.

コメント自動回答と解決待ちゲート

preview server 起動後に必ず実行する。手順 11 で Monitor ツールによる watch-comments を起動し、以下のフローでコメントの自動検知・回答・解決待ちを行う。

watch-comments の起動

preview server 起動後、以下で SSE イベント監視を開始する。

python3 -m scripts.html_review_workbench.cli watch-comments \
  --root <output-dir>

agent は Monitor ツールでこのプロセスの stdout を監視する。各行は 1 行 JSON のイベント。

自動回答フロー