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.

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

<!-- BEGIN SHARED: md-file-prohibition --> 設計資料作成は、.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 のようなプレーンテキスト名を使う。

<!-- END SHARED: md-file-prohibition -->

• 設計資料の本文は、見出し記号を含む原稿ではなく、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が設計構造を判断して文書モデルを直接作る。

<!-- BEGIN SHARED: html-style-classes -->

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> で列単位、または個別セルに付ける |

html
<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. <!-- END SHARED: html-style-classes -->

<!-- BEGIN SHARED: html-design-guidance -->

表現の質の指針

見た目の判断に迷った時は、次の 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). <!-- END SHARED: html-design-guidance -->

<!-- BEGIN SHARED: html-interactive-controls -->

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

読むだけでなく触って決める資料では、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 に落ち、どちらも使えない環境ではメモリ上だけで動く。操作そのものは止まらない。

html
<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.

html
<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. <!-- END SHARED: html-interactive-controls -->

<!-- BEGIN SHARED: mermaid-kinds -->

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 AInput] --> B{Decide} B -->|yes| CDo it] B -->|no| DSkip]

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. <!-- END SHARED: mermaid-kinds -->

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 イベント監視を開始する。

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

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

自動回答フロー

watch-comments から comment_updated イベントを受信したら:

1. イベント行の gate.needs_agent_review_threads を見る。ここに並ぶ thread id が、ユーザーが返信を待っているスレッドである。空でなければ必ず本フローを実行する。gate が open でも、それは「設計反映してよい」という意味だけで、「自分宛ての用件が無い」という意味ではない。
2. ingest-review --root <dir> で状態を保存する。ingest-review の実行だけで返信が追加されることはない。
3. 対象スレッドの comment と selected_text、および replies の全文（ユーザーが agent の返信の後に書いた再指摘を含む）を読み、設計資料の文脈を踏まえて実質的な回答を作成する。
4. add-reply --root <dir> --thread-id <id> --body "<reply>" で HTML コメントスレッドに書き戻す。これによりそのスレッドの status は needs_user_reply になり、gate から外れる。
5. 回答本文をコンソール（会話）にも出力する。ユーザーはブラウザとコンソールの両方で回答を確認できる。
6. 未解決のコメントにはまだ設計変更を適用しない。回答で受領を伝え、スレッド解決後に反映する旨を書く。
7. 自動回答が完了したら、設計変更には進まず停止する。

解決待ちゲート

IMPORTANT: ユーザーの返信待ち（status: needs_agent_review）のスレッドが 1 件でもある間は、設計反映（ドキュメント修正）に進まない。

ゲートの判定はコメント本文の解釈ではなく comments.json の status だけで行う。ユーザーが返信すると status は必ず needs_agent_review に戻り、agent が add-reply すると needs_user_reply になる。

修正判断の前に以下でゲートを確認する:

bash
python3 -m scripts.html_review_workbench.cli check-gates \
  --root <output-dir>

出力は常に全 key を含む:

json
{"gate": "blocked", "needs_agent_review_threads": ["cmt_x"], "resolved_threads": [], "status_counts": {"needs_agent_review": 1, "needs_user_reply": 0, "resolved": 0}}

• "gate": "blocked" → 設計修正を行わない。needs_agent_review_threads の各スレッドへの回答に専念する。
• "gate": "open" → resolved_threads の各スレッドを反映候補として検討してよい。反映すべき内容かどうかはスレッド全体を読んで agent が判断する。

スレッド解決時の反映フロー

ユーザーがスレッドを「解決」した comment_updated イベントを受信したら:

1. check-gates でゲートが open であることを確認する。
2. resolved_threads の各スレッドについて、スレッド全体の議論を読み、修正が必要か判断する。
3. 必要な修正を document model に適用する。
4. render CLI で再生成する。
5. notify-update --root <dir> --message "コメント反映済み" でブラウザに更新通知を送る。

修正完了のブラウザ通知

notify-update を実行すると、preview server 経由でブラウザに SSE イベントが送られ、画面上部にバナーが表示される。ユーザーは自分のタイミングでリロードして確認できる。自動リロードはしない。

bash
python3 -m scripts.html_review_workbench.cli notify-update \
  --root <output-dir> \
  --message "コメント反映済み。リロードして確認してください"

Automatic Comment Reply and Resolution Gate

After preview startup, monitor browser comment events with watch-comments. Each event line carries a gate object; gate.needs_agent_review_threads lists the threads that are waiting for your reply. On each comment_updated event, read those threads in full (including user replies posted after your own), run ingest-review, and write same-thread replies with add-reply. The gate is blocked while any thread has status needs_agent_review; gate: open only means design edits are allowed, never that there is nothing addressed to you. Before applying any document changes, run check-gates, then apply resolved_threads feedback to the document model, re-render, and use notify-update so the browser shows an update notice without forcing an automatic reload.

CodexでのCLI呼び出し

HTML生成時は、visual-html-renderer と同じ共通CLI入口を使う。 <!-- BEGIN SHARED: repo-root-resolution --> CLI実行前に、この SKILL.md の配置から renderer repo root を決める。 skills/reviewable-design-doc/SKILL.md の2階層上が renderer repo root であり、 そこに scripts/html_review_workbench/cli.py が存在することを確認する。 すべての python3 -m scripts.html_review_workbench.cli ... は renderer repo root を 作業ディレクトリにして実行する。現在のチャットやworkspaceのcwdをrepo rootとして扱わない。 cwdに scripts/html_review_workbench/cli.py が無い場合は、代替HTMLを作らず、 renderer repo rootへ移動してCLIを実行する。 <!-- END SHARED: repo-root-resolution -->

<!-- BEGIN SHARED: cli-commands-core -->

bash
python3 -m scripts.html_review_workbench.cli build-model \
  --text "<existing content when converting an existing source>" \
  --output <document-model.json>

python3 -m scripts.html_review_workbench.cli attach-image \
  --model <document-model.json> \
  --block-id <generated-image-block-id> \
  --image <generated-image-path>

python3 -m scripts.html_review_workbench.cli check-model \
  --model <document-model.json>

python3 -m scripts.html_review_workbench.cli render \
  --model <document-model.json> \
  --output <output-dir>

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

python3 -m scripts.html_review_workbench.cli preview \
  --root <output-dir> \
  --mode auto

<!-- END SHARED: cli-commands-core -->

<!-- BEGIN SHARED: preview-owner-pid-note --> Codex / Claude では preview コマンドを一回限りの shell から起動することがあるため、標準手順では --owner-pid を渡さない。preview server は 24時間アクセスが無い場合に idle timeout で自動停止する。長寿命の所有プロセスが明確に分かる場合だけ --owner-pid <pid> を使ってよい。一回限りの shell の $$ や $PPID は短命プロセスを指すため使わない。 <!-- END SHARED: preview-owner-pid-note -->

<!-- BEGIN SHARED: tailscale-sandbox-fallback --> Codex sandbox内で tailscale ip -4 が設定ファイル読み取りに失敗する場合は、visual-html-renderer と同じく python3 -m scripts.html_review_workbench.preview_host_resolve で取得したIPv4を HTML_REVIEW_WORKBENCH_TAILSCALE_IP に渡してから preview --mode auto を起動する。 <!-- END SHARED: tailscale-sandbox-fallback -->

preview が status: running を返した場合、レビュー依頼の最終応答に url を必ず含める。ファイルパスだけで完了しない。標準では --owner-pid を渡さず、24時間アクセスが無い場合に idle timeout で自動停止させる。長寿命の所有プロセスが明確な場合だけ --owner-pid <pid> を使う。

レビュー取り込み時は、最新のpreview sessionまたはユーザー指定の成果物rootから annotations/comments.json を読み込む。

bash
python3 -m scripts.html_review_workbench.cli ingest-review \
  --root <output-dir>

回答・受領・確認依頼が必要なコメントへagent replyを書き戻す場合は、ingest-review の分類結果から対象thread idを確認し、同じ成果物rootへ add-reply を実行する。

bash
python3 -m scripts.html_review_workbench.cli add-reply \
  --root <output-dir> \
  --thread-id <thread-id> \
  --body "<agent reply body>"

document modelへ反映する場合は、完全一致置換に限定して明示的に実行する。

bash
python3 -m scripts.html_review_workbench.cli ingest-review \
  --root <output-dir> \
  --model <document-model.json> \
  --apply-model

解決待ちゲートの確認:

bash
python3 -m scripts.html_review_workbench.cli check-gates \
  --root <output-dir>

コメント変更の SSE 監視（Monitor ツールで stdout を監視する）:

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

ドキュメント更新通知をブラウザへ送信:

bash
python3 -m scripts.html_review_workbench.cli notify-update \
  --root <output-dir> \
  --message "コメント反映済み"

CLI Usage in Codex

Use the same shared CLI as visual-html-renderer. Resolve the renderer repo root from this SKILL.md: two levels above skills/reviewable-design-doc/SKILL.md. Run every python3 -m scripts.html_review_workbench.cli ... command from that repo root. If the current workspace does not contain scripts/html_review_workbench/cli.py, move to the renderer repo root instead of creating fallback HTML. Use ingest-review, add-reply, check-gates, watch-comments, and notify-update for review cycles.

完了時の確認

• index.html と renderer-manifest.json が生成され、validate が status: ok を返している。
• check-model が status: ok 相当の成功終了を返している。
• preview有効時は、レビュー用URLをユーザーへ提示している。
• レビュー取り込み後、annotations/review-cycle-state.json が生成されている。
• 回答・受領・確認依頼が必要なコメントには、add-reply によりHTMLコメントスレッド上のagent replyが追加されている。
• コメント反映でユーザー確認が必要な場合は、チャットだけでなくHTMLコメントへ返信済みであることを確認している。

実シナリオ検証

自動テスト pass と CLI の JSON 出力確認は、実シナリオ検証ではない。「動作確認」を求められた場合、以下のエンドツーエンドフローを実行する。

レビュー取り込み・返信の検証

1. ユーザーが HTML 上にコメントを入れたことを確認する（ユーザーからの報告を待つ）。
2. ingest-review で comments.json を取り込み、分類結果を読む。
3. 各コメントの comment と selected_text を読み、設計資料の該当箇所の文脈を踏まえて、コメントの意図を理解する。
4. 回答・受領・確認依頼が必要なコメントに対して、コメント内容に対する実質的な返答を考え、add-reply で HTML コメントスレッドに書き戻す。
5. ユーザーに返信した旨を伝え、ブラウザで表示と内容の両方を確認してもらう。

検証の完了条件: ユーザーがブラウザ上で agent の返信を読み、内容と表示の両方が意図通りであることを確認した時点。CLI が正しい JSON を返したことではない。

Real Scenario Verification

Passing unit tests and receiving valid CLI JSON are prerequisites, not real scenario verification. For an operational check, the user must add a browser comment, the agent must ingest it, read comment and selected_text, write the actual answer with add-reply, and the user must confirm in the browser that both the reply text and display are correct.

ガード

• 設計として未確定の内容は確定事項と分けて書く。
• レビューコメント機能は必須で有効化する。
• IMPORTANT: レビューコメントに回答する時は add-reply で HTML コメントスレッドに書き戻す。チャットで回答内容を述べただけでは回答完了にならない。
• HTML低レベル実装をこのskillに重複実装しない。
• IMPORTANT: comments.json を Edit ツールや直接のファイル編集で変更してはならない。コメントの追加・返信は必ず add-reply CLI 経由で行う。CLI はスキーマ検証を通すため、不正なデータがファイルに書き込まれることを防ぐ。

Guards

Separate unresolved design ideas from confirmed decisions. Keep review comments enabled. When answering comments, use add-reply to write back into the HTML thread; a chat-only answer is not completion. Do not duplicate low-level HTML implementation inside this skill.

IMPORTANT: Never edit comments.json directly with the Edit tool or any file-writing tool. All comment mutations must go through the add-reply CLI, which enforces schema validation and prevents malformed data from being written.

禁止事項 / Prohibited Actions

以下の操作は明示的に禁止する。違反するとデータ破損やレビュープロセスの破綻を引き起こす。

1. comments.json を Edit/Write ツールで直接変更すること。reply の追加は add-reply CLI のみ。
2. check-gates が blocked を返している状態で document-model.json を変更すること。
3. ingest-review の出力に "gate": {"gate": "blocked", ...} が含まれている状態で設計変更に着手すること。
4. render の stderr 警告を無視して次のステップに進むこと。
5. gate が open であることを根拠に、コメントの中身を読まずに「自分宛ての用件は無い」と判断すること。返信要否は needs_agent_review_threads で判断する。

The following actions are explicitly prohibited. Violations cause data corruption or review process breakdown.

1. Editing comments.json directly with Edit/Write tools. Use add-reply CLI only.
2. Modifying document-model.json while check-gates returns blocked.
3. Starting design changes when ingest-review output contains "gate": {"gate": "blocked", ...}.
4. Ignoring render stderr warnings and proceeding to the next step.
5. Concluding "nothing is addressed to me" from gate: open without reading the comments. Reply obligations are decided by needs_agent_review_threads.