# Bizdoc

> ビジネスシーン向けの白基調・SVG図解付き1枚HTML文書（提案書/報告書/解説/手順書/議事録）を生成し、doc-hub に保存する。「bizdoc」「ビジネス資料作って」「ビジネス文書」「業務資料作って」「提案書作って」「報告書作って」「報告書をHTMLで」「白基調で資料」「図解入りの業務資料」「◯◯の資料をまとめて」「business document」で発動。イラスト風でない業務文書・関係部署に展開する資料が必要なときに使う。住み分け — 図解・画像の単体生成は codex-imagegen / svg-diagram、カジュアルな解説ページは run-explainer-page、発表スライドは frontend-slides。「文書一式」を作るのが本スキル。

- Skill: `haboshi/bizdoc` (Agent Skill)
- Install (CLI): `npx skillmds@latest add haboshi/bizdoc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haboshi/bizdoc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: haboshi (https://skillmd.com/u/haboshi)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/haboshi/bizdoc

---


# bizdoc

ユーザー入力（topic 文字列 / URL / ローカルファイルパス / 直前会話）を起点に、**白基調・図解付き1枚 HTML のビジネス文書**を生成し、doc-hub（`node "${CLAUDE_PLUGIN_ROOT}/scripts/hub.mjs"`）に保存する orchestrator。

## 1. Input / Output

- **Input**: `$ARGUMENTS` = topic 文字列 / URL / ローカルファイルパス のいずれか。空または曖昧なら直前会話を context として拾う。
- **Output**: doc-hub に保存済みのドキュメント。保存先パスは Phase 5 の `hub.mjs add` の stdout（保存先 `index.html` の絶対パス1行）で確定する。会話の最後にこのパスをユーザーへ提示する。
- **副産物（doc-hub には保存しない）**: 調査結果 `context.md`、構成案 `outline.json`。スクラッチ領域の一時ファイルとして扱い、doc-hub に保存するのは組み立て済みの最終 HTML のみ。

## 2. 最重要（compaction 対策）

- **1 ターンで Phase 0〜5 を完走する**（フェーズ間で応答を終了しない）。Phase 0 の目的・読者・種別が会話から一意に定まる場合は AskUserQuestion で止めず即着手する。
- **1枚 HTML 縛り**（CDN 禁止。CSS は `<style>` にインライン、SVG も文書内にインライン。外部ファイル参照や `<link>` での読み込みはしない）
- **図解の既定は gpt-image-2（B2 高密度インフォグラフィック）** — 次点 drawio（厳密文字・再編集要件）、手書き SVG は型に収まる単純図のみ（2026-08-20 オーナー決定）。**適していると判断したら確認せずに使う**（1ターン完走を止めない）。基準と spec は §7

詳細な落とし穴は §11 Gotchas に集約する。

## 3. いつ使う / いつ使わない

| 用途 | 使うスキル |
|---|---|
| **図解付きビジネス文書（提案書・報告書・解説・手順書・議事録）を関係部署に展開** | **`bizdoc`** ← この skill |
| カジュアルな図解解説ページ（技術ネタ・個人の理解用） | `run-explainer-page` |
| スライド（HTML/PDF） | `frontend-slides` |
| Markdown 資料の PDF 化 | `pdf-creator-jp` |

判断基準: 「業務の意思決定・報告・引き継ぎに使う、フォーマルな文書か」= bizdoc。「わかりやすさ優先のカジュアルな解説か」= run-explainer-page。

## 4. Phase 0: 目的確定

会話から次の4項目を確定する。ここで確定した内容が `.cover`（表紙相当）の中身になり、Phase 2 で各ブロックに書く `why` の判定基準になる。

1. **目的**（なぜ作るか。例: 予算承認を得る／進捗を共有する／手順を周知する）
2. **読者**（誰が読むか。例: 経営層／情報システム部／現場担当者）
3. **文書種別**（提案書 / 報告書 / 解説 / 手順書 / 議事録 のいずれか、または相当するもの）
4. **トーン**（フォーマル度・断定の強さ。読者との関係性から判断）
5. **決裁レイヤー判定**（会話から自動判定。質問しない）: 目的に「承認を得る・決裁を仰ぐ・予算を獲得する」が含まれるか。含まれれば決裁レイヤー on（exec-summary への依頼1項目・終端の判断材料ブロック・cover meta の宛先/版数。本文の構成規範は変えない — §6 のモード表参照）。含まれなければ**理解優先の既定構成のみ**で作る。あわせて**読者の抵抗**を判定する: 結論が読者の既存方針・利害と対立する題材なら高抵抗とし、exec-summary の項目を「発見」に留めて推奨を終端の判断材料ブロックへ置く

4項目が会話から一意に定まらないときだけ、AskUserQuestion で1問に絞って確認する。選択肢は「種別 × 読者」の組合せ候補（例: 「提案書・経営層向け」「報告書・現場向け」等）にし、自由記述の余地も残す。定まっているときは質問せず即 Phase 1 へ進む（§2 の1ターン完走を優先）。

## 5. Phase 1: 調査

入力をパースし、以下のいずれか or 両方の subagent を起動する。**親は要約だけ受け取り**、探索結果の全文を主コンテキストに吸わせない。

### 判定ルール

- 入力が**社内のコードベース・システム・ローカルファイル**に関する題材 → `Explore` エージェント
- 入力が**抽象的なトピック・社外事情・市場動向**など → `general-purpose` エージェントによる web research
- 両方ありうるなら **1 メッセージで並列 fire**

### Explore エージェントの呼び方（コードベース・社内システム題材）

```
Agent({
  description: "bizdoc Phase 1 code research",
  subagent_type: "Explore",
  prompt: "<対象コードベース/システムで何を読んで欲しいか具体的に。例: '<repo>の認証まわり\
           (src/auth/*) を読んで、報告書の読者（情報システム部）が知りたい実装状況・\
           残課題を300語以内で。数字（件数・所要時間等）は取得元を明記して。仕様書や\
           コメントの文は自分の言葉に言い換え、原文のまま残すのは短い語句 1 つまで'>"
})
```

### Web research subagent の呼び方（抽象トピック・社外事情）

```
Agent({
  description: "bizdoc Phase 1 web research",
  subagent_type: "general-purpose",
  prompt: "<下記の指示文をそのまま渡す>"
})
```

指示文テンプレ:

```
あなたはビジネス文書（種別: <Phase0で確定した種別>）作成のための調査役。
トピック: 「<TOPIC>」/ 目的: <Phase0で確定した目的> / 読者: <Phase0で確定した読者>

以下を500語以内のサマリで返す:
1. 読者が前提として知っておくべき事実（3-5点）
2. 数字（価格・実績・比較値等）— 必ず出典 URL と取得日を併記する。出典が確認できない数字は
   「未確認」と明記し、断定形で書かない
3. 論点・リスク・反対意見になりうる材料
4. 意思決定や行動を後押しする材料（推奨・比較の根拠になりうるもの）
5. 図解にできそうな構造（比較・時系列・構成・手順・関係・分類 のどれに近いか）

6. 出典の言葉の扱い: 各ソースの内容は自分の言葉で 1〜2 文に言い換える。原文のまま残すのは「」付きの短い語句を
   1 つまでとし、出典（URL・取得日）を添える。正解例（1 行）:
   　同社の決算説明資料（URL, 2026-09-03 取得）は国内売上の伸びを主因に挙げ、業界誌の解説記事（URL, 2026-09-03 取得）は同じ数字を「一時的な特需」と評した。
   — 2 つの出典を間接話法で対比し、原文のまま使ったのは「」付きの短い語句 1 つだけ。

出力はマークダウン書式。親が context.md に統合する。
```

### 縮退モード

Agent ツールが使えない文脈（自分がサブエージェントとして実行されている等）では、subagent を起動せず自分で調査して `context.md` を書く: ローカル題材は Read / Grep で読み、社外事情は WebSearch / WebFetch で公式情報を取得し、上記 6 項目（出典の言葉の扱いを含む）を自分で埋める。

### context.md への統合

subagent の要約（または縮退モードでの自前調査）を、スクラッチ領域の `context.md` に統合する。数字には必ず出典 URL と取得日を添える（出典なしの断定は禁止）。

## 6. Phase 2: アウトライン

`context.md` を読んで `outline.json` をスクラッチ領域に Write する。**構成は毎回ゼロから設計し、順序付きの章立てテンプレは書かない**（「提案書は背景→課題→提案→効果→費用の順」のような固定型を持ち出さない）。

必須要素はビジネス文書の作法として次の2つだけ:

1. **表紙相当**（タイトル・日付・目的・読者。`.cover` で表現する）
2. **結論先出し**（`.exec-summary`。文書の要点を冒頭で言い切る）

それ以外の構成は `${CLAUDE_PLUGIN_ROOT}/templates/components.md` を**伝達目的**（比較させる／時系列・計画を示す／判断を促す／根拠・数値を示す／全体像を掴ませる／手順を追わせる／注意を促す／規模感・絞り込みを示す／関係・体制を示す）で毎回引き、その文書の目的・読者に効くブロックだけを選ぶ。**各ブロックに `why`（目的・読者にどう効くか1行）を必須とし、書けないブロックは削る**。

### 構成規範（「チープな構成」の禁止則）

- **見出しはメッセージにする**: 各セクションの見出しは「読者への主張を言い切る文」にする（例: 「品質は目視の頑張りではなく、2つの決定論ゲートが守る」）。トピックラベル（「背景」「構成」「使い方」「まとめ」）を見出しにしない
- **見出しのレジスター（文体水準）を縛る**: 「メッセージにする」は主張の強さの規範であり、圧縮の免罪符ではない。**以下の各則は見出し1本ごとに評価し、文書全体で機械的に同時充足させない**（v0.9.0 — 全節で満たそうとすると構文が収束する。下の「構文を散らす」を参照）。A/B 実測で bizdoc 見出しの認知負荷が高いと評された残存要因は、格式を漢語の圧縮で出そうとする癖にある — 格式は内容の確かさで出す。対象はセクション見出し（`h2`・outline の主張文）のみで、§8 の目次短縮形（25字要約・体言止め可）は対象外
    - **1見出し1主張**: ダッシュ（—）の後ろに置けるのは主張の補強・限定まで。独立した2つ目の主張は `.sec-lede` か本文へ落とす（または節を分ける）
    - **用言で言い切る**: 体言止め・名詞化（「〜の拡大」「〜済み」「〜の活用開始」）をやめ、動詞で終える（「〜が増えた」「〜を確認する」）。断定の常体で書けば口語にはならない
    - **未解決要素を1つ残す**: 見出しは主張文のまま、本文が回収する未解決要素（なぜ／どうやって／何を捨てたか）を1つ残す。目次を上から読んだとき全見出しが「答えの言い切り」で完結している outline は差し戻す（見出しを読んだ時点で本文を読む理由が消える）
    - **疑問形の許可**: 読者が自発的に抱かない問いを文書側が起こす節では、疑問形見出し（「なぜ〜のか」— 用言終止として合法）を使ってよい。その場合 `.sec-lede` に1行の答えを必ず置く。**節数のおよそ3分の1まで**（v0.9.0 で1〜2節から緩和）。答えの伴わない問いは引き続き禁止
    - **構文を散らす（v0.9.0）**: 上の各則を全見出しで同時に満たそうとすると、構文が1つに収束する。実測（7節の報告書）で**7見出しすべてが「Xは〜する」の平叙断定になり、うち3つが否定・逆接で終わった** — 個々は規範を満たしているのに、目次で並ぶと単調になる。**同一構文が3節連続したら、そのうち1つを別の型へ替える**。使える型は次の3つ:
        - 平叙断定（既定。「原価は QR が読まれた回数で動く」）
        - 疑問形（上記の許可枠内。「なぜ上限に当たっても気づけないのか」）
        - **機能ラベル**（「1本あたりの内訳」「判断が要る3点」）— 下の許可条件を満たす節に限る
    - **機能ラベル見出しの条件付き許可（v0.9.0）**: 「トピックラベル禁止」は、**主張を持てる節が主張を放棄すること**への禁止であって、主張が本来無い節にまで断定を強いる則ではない。次の**いずれか**に当てはまる節は機能ラベルにしてよい:
        - **一覧・カタログの節** — 内訳表・確度一覧・用語集など、読者が「探しに来る」節（主張は既に別の節が述べている）
        - **判断材料を並べる節** — 選ばせるのが目的で、書き手が1つに決めない節
        - **構文の反復を断つため**（上記「構文を散らす」の適用）
      許可した場合も `.sec-lede` は主張文で書く（節が何も主張しない状態は作らない）。この3条件のどれにも当たらない節でのラベル化は、従来どおり禁止
    - **骨格可読性**: 見出し＋sec-lede だけの拾い読みで文書の論旨が再構成できること（Phase 5 の検査項目）
    - **漢語のアドホック連結禁止**: 漢字5字以上の連結語は、一語として定着した語（「費用対効果」等）・固有名詞・数値単位を除き見出しに置かない。「分析対象範囲拡大」型の即席連結は動詞へ開く（「分析する範囲が広がった」）
    - **長さ上限**: 見出し全体で全角35字以内、ダッシュ前の主節は20字以内を目安。超えるときは語を削って圧縮するのではなく、主張を1つに絞る
    - 改稿例: 「費用増の原因は特定済み — モデルの問題ではなく、分析対象の拡大」→「費用が増えた原因は、モデルではなく分析対象が増えたことにある」／「効果は月額 −42%（試算）— 停止分の費用削減と、用件分類の活用開始を同時に行う」→「費用は試算で月額 42% 下がる」（ダッシュ後半は `.sec-lede` へ落とす）
- **ピラミッドを張る**: `.exec-summary` の各結論は、それを支える本文セクションを最低1つ持つ。どの結論とも対応しないセクションは、削るか結論側に昇格させる
- **1セクション = 1メッセージ、1画面 = 1ビート**: 見出しの主張を超える話題を同じセクションに詰めない。各節はおおよそ1ビューポート（900px 目安）を1ビートとし、節の完了条件（この画面を読んだら読者が言えること）を1つだけ持つ。2つ言えるなら節を分割する。同一画面に新しい用語・新しい因果・例外を同時に出さない（例外・注記は次ビートか付録へ）
- **`.sec-lede` は半歩先のスポイラー**: 見出しの主張の「意外な一点」（何が常識と違うか・何を変えないか）を1行で書く。手続き文（「〜を要約します」）・免責・換算前提はここに置かない（本文末尾か出典行へ）。決裁レイヤー on のときは二重契約 — 逐次読者への半歩先スポイラーであると同時に、途中参入する決裁者が「この節の問いと答え」を局所復元できる形にする
- **密度規範（床と波形）**: スクロール1画面（目安 900px）ごとに視覚要素（図・表・カード・KPI）を最低1つ置き、ベタ段落だけのセクションを作らない（床）。加えて**密度の山は1節1つまで**とし、高密度要素（表・コード・複雑図）の直前に1行のフレーム（何を見るか）、直後に1行の回収（「つまり〜」）を置く。情報を削って密度を下げるのではなく、**到着レートを波形で整形する**
- **視覚要素の役割固定**: 図=構造、表=数値比較、callout=判定・洞察（「この表の下2行が設計の芯」）と役割を分け、同役ブロックの連続（kpi-grid 直後の table 等）を禁じる。callout はセクション末の判定・洞察専用スロットとし、コンプライアンス注記・手続き連絡を置かない。**callout は器幅（表・図と同じ右端）で組まれるため本文は4行以内**に収める — 超えるなら本文段落か `.card` へ移す
- **初手は構造図**: 文書の最初の視覚要素は数値カード群でなく構造図（Before/After・全体像）にする。kpi-grid は読者が構造モデルを得た後の効果まとめ・実績報告に限る。新出概念が3つ以上ある文書は、最初の構造図を「登場概念のラベル付き地図」を兼ねる形にし、専門用語の初出を図中ラベルと同時にする（本文だけで定義しない）
- **前方参照禁止・証拠はその場**: 「詳細は後述」「（N章）」「（別紙N）」のみを根拠として表セル・本文に置くことを禁止する。品質・効果の主張には、その場で最小の裏どり（実測値1つ＋確認手段1語）を添える。集約評価の節は置いてよいが、証拠の初出の場にしない。**後方参照も同じ**: 「節Nの図で見たとおり」で根拠を運ばず、必要な値・判定は1句でその場に再掲する（ブラインド審査の実測で、審査員2名が同一の後方参照箇所を往復として計上した）
- **タイトルの数値は本文と同じ丸め**: 見出しや表題で「半分」等に丸めた数値が本文の実数（42% 等）と食い違うと、読者は照合の往復を強いられる（同・審査実測）。丸めるなら本文も同じ語で通し、実数を使うならタイトルも実数にする
- **読者に演算・照合をさせない**: 同一事実は1つの単位系で示し、換算・検算（増加率の積・円換算等）は書き手が済ませて結果だけ添える。番号参照（「施策②」等）は定義の後にのみ使う。表・図・終端に出る語の初出には1句の説明を付ける
- **短い呼び名**: 反復参照される系・コンポーネント・施策が2つ以上あるときは、初出（できれば表の先頭列）で短い呼び名（A/B・①②③等）を与え、以後それで通す。字面の似た長い複合名を無短縮で反復しない
- **手続き隔離と結論ブロック**: 手続き情報（機密表示・宛先・版数・承認事項・添付一覧・期限約束）は `.cover` の meta 行と終端の2箇所に隔離し、exec-summary・sec-lede・callout に混ぜない。文書末尾には exec-summary の各項を1行ずつ回収する**結論ブロック**（`.conclusion` — ダーク地の終端パネル）を置き、手続き・残課題で文書を終えない（承認節・残課題節の後に結論を置く）。冒頭の `.exec-summary` を終端に再利用しない — 地図（冒頭）と締め（終端）は視覚で区別する
- **redundancy と橋のスコープ**: 同一内容をリード・本文・図キャプションで繰り返さない（黙読文書の冗長は純粋な外在負荷）。ただし**節の橋は例外**: 節冒頭で直前の節の結論を1行以内で再掲して受けるのは接続装置であり冗長ではない
- **本編と付録の二層化**: 本編は結論・根拠・図で完結させ、経緯・例外・手法・生データは**付録節**へ隔離する。`<details>` は画面向け補足に限定し、印刷必須の情報を入れない（Chromium は閉じた `<details>` を印刷でも展開しない）。付録は「読まなくても本線は閉じる」と明示する

### 配置規範（「読みにくい」の実測要因への対処）

同一トピックで run-explainer-page 出力と A/B 実測した結果、bizdoc が「難しい」と評された原因は
文章量でも文の長さでもなく（実測: 本文 4,247字 対 4,426字、1文の中央値 33字 対 40字といずれも bizdoc の方が簡潔）、
**冒頭の重さと、表への長文詰め込み**だった。次の2つを数値規範として守る。

- **冒頭要約の予算**: `.exec-summary` は **3項目・各1文**を既定とする。`<small>` の補足を付けるのは
  **多くても1項目**まで（実測: 全項目に付けた文書は冒頭だけで 576字あり、explainer の TL;DR 203字の
  2.8倍で、文書中で最も重いブロックになっていた）。補足したい内容はピラミッド原則上それを支える本文
  セクションが必ずあるので、そちらへ落とす
- **表セルの上限**: `<td>` は **40字以内**。列数は **4列を上限**とする。表幅は本文より広いが列で割られるため
  （4列なら1列 ≈ 190px・`font-size: 13.5px`）、40字を超えるセルは必ず3行以上に折り返して「一覧して比べる」
  機能を失う。超える説明は本文の `<p>` か `.card` へ移し、表には結論だけを残す

- **数値の泣き別れを作らない（執筆時）**: 数値と直後の助数詞・和文は詰めて書く（「9回」「97件」「2週間」— 間の半角スペースは折返し点になり「4 /回」型の泣き別れを生む）。「約・月・年 + $金額」のような分離できない和欧の組は `&nbsp;` で繋ぐ（「約&nbsp;$4,730」）。それ以外の和欧間スペースは通常どおりでよい（折れても泣き別れにならない）

**文の長さの規範は置かない** — 上記のとおり実測で bizdoc の文は既に簡潔であり、本文の文を短くする規範を
足すと事実に反する矯正になる。直すのは器（版面・配置）と見出しのレジスター（構成規範を参照）であって、
文の長さではない。

### 言葉づかいの規範（v0.9.0 追加。長さではなく語の選び方）

器は数値で縛るのに文章には一切規範が無い、という非対称が v0.8 まで残っていた。結果として
版面は毎回整い、**言葉の質だけが書き手ごとにぶれる**。以下は文を短くする則ではなく、
同じ長さのままどちらの語を選ぶかの則である。

- **読者の語で書く**: 読者が普段その物事を呼ぶ名前を使い、実装側の呼称に寄せない
  （「QR が読まれた回数」であって「セッション発行数」ではない。「上限に当たる」であって
  「予算リミットに到達する」ではない）。社内の実装名・テーブル名・変数名を本文の主語にしない
  — 出所として示すときは `<code>` と `.src` 行に置く
- **具体が抽象に勝つ**: 「大幅に削減」「柔軟に対応」「適切に管理」を、数値・固有名・動作に置き換える。
  置き換えられないなら、その一文は**まだ何も言っていない**ので削る
- **主語を立てる**: 「〜が行われる」「〜と考えられる」を避け、誰が・何がそうするのかを書く。
  受動で書いてよいのは、主体が本当に問題でないときだけ（「上限は DB 側で締めてある」は可）
- **一度だけ言う**: 見出し・`.sec-lede`・`.callout` は器が近接しているため、同じ主張を
  3回書きやすい（実測: 1つの節で見出し「障害としては見えない」／lede「警告として出ない」／
  callout「何も起きていないように見える」の三重反復）。**同じ節の中で主張を言い換えて繰り返さない** —
  見出しが主張、lede が意外な一点、callout が判定・含意と、**役割で書き分ける**
- **修飾を疑う**: 「非常に」「極めて」「まさに」「〜的」「〜性」は、無くても意味が変わらないなら削る。
  強調は語ではなく事実の並べ方で作る
- **カタカナ語は言い換えを1度試す**: 定着語（コスト・リスク・データ）はそのまま使ってよい。
  「アグリゲート」「ジャストアイデア」型は日本語へ開く

**これは推敲の則であって、執筆を止める則ではない。** 書き上げてから Phase 5 の骨格検査と
合わせて1度通す（書きながら1文ごとに点検すると筆が止まり、かえって痩せた文章になる）。

### 文書種別ごとの「読者が最初に知りたい問い」（構成のヒント。順序ではない）

構成を組み立てる前に、この文書の読者が最初に何を知りたがるかを自問する。以下は例であり、固定の章立てではない — 実際の問いは Phase 0 の目的・読者に応じて毎回立て直す。

| 種別 | 読者が最初に知りたい問い（例） |
|---|---|
| 提案書 | 「結局いくらで何が良くなるのか」「なぜ今か」「リスクは何か」 |
| 報告書 | 「結論はどうだったか」「次に何をするのか」 |
| 手順書 | 「自分は何をすればよいか」 |
| 解説 | 「これは何か」「なぜ重要か」「自分に何が関係するか」 |
| 議事録 | 「何が決まったか」「誰が何をいつまでにやるか」 |

### outline.json の形

```json
{
  "slug": "kebab-case-slug",
  "type": "提案書",
  "approval_layer": false,
  "budget": { "sections": 6, "figures": 4, "raster": 1 },
  "cover": {
    "title": "...",
    "date": "2026-07-31",
    "purpose": "Phase0で確定した目的",
    "reader": "Phase0で確定した読者"
  },
  "exec_summary": {
    "why": "結論を冒頭で言い切ることで、多忙な読者が本文を読まなくても要点を掴めるため",
    "points": ["...（各項目に本文でしか解けない緊張語を1つ残す）"],
    "request": "決裁レイヤー on のときだけ: 何をいつ承認してほしいか1文"
  },
  "blocks": [
    {
      "purpose_key": "根拠・数値を示す",
      "expression": "kpi-grid",
      "why": "<この目的・読者にどう効くか1行>",
      "q": "<この節が回収する読者の問い（前節が開いたもの）1行>",
      "opens": "<この節の締めが次節へ開く問い1行。最終節は空でよい>",
      "content": { "...": "..." }
    }
  ]
}
```

`budget` は器の予算（節数・図の枚数）を生成前に宣言するもの。超過したときは**情報を削らない** — extraneous（冗長・帳簿仕事・装飾）を削るか、情報を付録へ移すか、図を分割する（生成文書は放置すると饒舌側に膨らむため、予算は「足す」でなく「移す・整形する」編集を強制する装置）。

アクセント色は outline.json では決めない（Phase 4 で hub 側の既存プロジェクト状態を見て決める。§8 参照）。

`blocks` の並びは主題の分類でなく**読者の問いの発生順**で決める（固定順は持たない）。位置 X の読者は X より上で確立したことしか知らない前提で書く。outline 段階で次の2つを検査する:

1. **question chaining 検査**: 各節が末尾に残す問いを1行ずつ書き出し（outline.json の `opens`）、次節の見出しがその問いを受けているか（次節の `q`）確認する。受けない節は並べ替えるか接続文を足す
2. **反論の即時回収**: 主張が誘発する最強の反論（「なぜもっと安い案にしないのか」等）は評価章へ先送りせず、その主張の直後に専用の節を立てて回収する

`expression` は `components.md` に列挙された表現名（`kpi-grid` / `compare-cols` / `steps` / SVG パターン名 等）を使う。

## 7. Phase 3: SVG 図解

`outline.json` の `blocks` のうち SVG 表現を選んだものについて、埋め込む前に必ず `${CLAUDE_PLUGIN_ROOT}/templates/svg-patterns/README.md`（全パターン共通の予防則。現在10項目）と、該当パターンファイル（例: `${CLAUDE_PLUGIN_ROOT}/templates/svg-patterns/process-flow.md`）を Read してから書く。

- 各パターンファイルが定めるラベル文字数上限を守る（超える場合はラベルを短くするか図を分割）
- 図の密度規範（副ラベル・順路・終端判定・実データ標本・1点強調）は `svg-patterns/README.md` **予防則11〜15** に従う
- 色は `var(--accent)` 等 tokens.css の CSS 変数で参照する（アクセントは1色のみ。唯一の例外が `var(--warn)` で、超過・未達・要対処の1要素にだけ使える。予防則5）
- 同一文書内に複数の SVG を貼るときは `marker id` の衝突がないか確認する（README.md 参照）
- `kpi-cards` は SVG ではなく `.kpi-grid`（HTML）に委譲するパターンなので Phase 4 で直接組み立てる

### 図解手段の選び方（既定は gpt-image-2。2026-08-20 オーナー決定）

**優先順位は gpt-image-2 → drawio → 手書き SVG**（3案比較でオーナーが確定した順序）。
選んだら確認を挟まず使う（判断を人に投げない）。

| 優先 | 手段 | 向いている図 | 引き受けられないもの |
|---|---|---|---|
| 1 | **gpt-image-2**（codex-imagegen・B2 spec） | ほぼすべての図解。フロー・比較・構成の高密度インフォグラフィック。質感と一目の魅力が最大 | 表・コード片・統計値の羅列（文字精度が構造的に弱い）。後から文言だけ直す予定の図（部分修正不能） |
| 2 | **drawio**（drawio-bridge 経由） | 金額・コード等の厳密文字が主体の図。ER・シーケンス・公式アイコン（AWS 等）。納品後に人が draw.io で直す図 | 質感・情緒。編集可能性は最大 |
| 3 | **手書き SVG** | `svg-patterns/` の型にそのまま収まる 3〜6 要素の単純図で、文書内の様式統一を最優先したいとき | 型に収まらない構図（座標が破綻する） |

判断の順序:

1. **まず gpt-image-2（B2 spec）で作れないか考える** — 「ラスタ=文字なしの雰囲気画」という旧運用は廃止。正確な日本語ラベル・副ラベル・数値・判定マーク入りの高密度インフォグラフィックを作らせる（【入れる文字】一字一句列挙方式）
2. **gpt-image-2 を降りるのは次の3つだけ**（いずれも drawio へ）: (a) 金額・件数・コードなど**一字も間違えられない文字**が図の主体 (b) 公開後に**文言修正が入る見込み**が具体的にある (c) 文字化け検査に**2回連続で落ちた**
3. 手書き SVG は「型に完全に収まり、かつ文書内の他の SVG と様式を揃えたい」ときの選択

**枚数の目安**: 1文書あたり gpt-image-2 1〜3枚を基本に、drawio 0〜2枚・手書き SVG 0〜2枚。
**生成物の検品**: gpt-image-2 の図は Read で目視し、日本語の文字化け・指定外ラベルの混入・情報の薄さを検査する（不合格は再生成2回まで → drawio に切替）。

### drawio で図を作る

経路は 2 つ。**Mermaid で書いて変換**（自動レイアウト。フロー・シーケンス・ER 向き）か、
**確定座標で組む**（AWS 構成図のように列と帯で並べる図。`drawio-bridge` の `xml-builder.js` と
`references/layout-rules.md` に従う）。どちらも後段の検証・変換・整形・検品は **`drawio-bridge` に任せ、
自前で SVG を整形しない**（2026-09 実測: 手動で id を付け替えた SVG は AWS アイコンのタイルが消えた。
draw.io は勾配の塗りを属性と `style` の両方に書き、片方だけ付け替えると勾配が失われる）。

#### drawio-bridge の所在（未導入なら導入する）

```bash
DB=$(ls -d "$HOME"/.claude/plugins/cache/haboshi-skills/drawio-bridge/*/ 2>/dev/null | sort -V | tail -1)
# 未導入なら: /plugin install drawio-bridge@haboshi-skills
# 導入できない環境では、配布元リポジトリ（claude-code-skills）の drawio-bridge/ を DB に指定する
[ -d "$DB/node_modules" ] || npm install --prefix "$DB" --silent   # 初回のみ（配布物に node_modules は無い）
node "$DB/scripts/drawio.js" --help
```

`drawio-bridge` も配布元も無い環境では「drawio-bridge が無い」と報告し、gpt-image-2 か手書き SVG に切り替える。
draw.io Desktop（`brew install --cask drawio`）は `export` と `check-overlap` の `.drawio` 入力に要る。

#### 手順（決定論ゲート 3 つ）

```bash
# Mermaid 経路: .mmd → .drawio（自動レイアウト）
node "$DB/scripts/drawio.js" export --in fig1.mmd --out fig1.drawio --format xml
# 座標経路: xml-builder.js で .drawio を生成（references/examples/aws-architecture.example.js が完成例）

node "$DB/scripts/drawio.js" validate --in fig1.drawio                              # ゲート 1: 構造
node "$DB/scripts/drawio.js" export   --in fig1.drawio --out fig1.svg --no-embed
node "$DB/scripts/drawio.js" check-overlap --in fig1.svg                            # ゲート 2: 重なり 0 件まで座標を直す
node "$DB/scripts/drawio.js" inline   --in fig1.svg --id-prefix fig1 --max-width 1050 --out fig1-embed.svg  # ゲート 3: 埋め込み整形
```

- `check-overlap` は辺×ラベル・ラベル×ラベルの交差を列挙し、あれば exit 1。**0 件にしてから PNG を目視する**。
  目視で直すのは色と語だけにする（座標は機械判定に従う）
- `inline` は width/height の除去、id の付け替え（属性と `style` 内の `url("#…")` の両方）、日本語フォント、
  色のライト固定を行う。draw.io の素の SVG は閲覧環境がダークだと線が白く飛ぶ（検品の Chrome でも起きる）
- `--max-width` は figure の器幅 918px に対する上限。**font-size 16 の図は viewBox 幅 1050 まで**（実表示 14px）。
  超えるなら図を分けるか、viewBox 座標系の font-size を上げる（予防則 9）
- `--id-prefix` は図ごとに変える。同じ HTML に 2 枚貼ると id が衝突する

#### 埋め込み

整形後の SVG をそのまま `<figure>` に貼る（viewBox 基準なので `figure svg { width:100% }` が効く）。
例外は 2 つ。SVG が 1MB を超える場合（AWS アイコン 40 個で約 1.8MB。保存物が重くなる）と、
公式アイコンを画像として渡す方が読み手に確実な場合は、`export --format png --border 12` の PNG を
`<img>` で埋める。PNG は編集できないので、`.drawio` を文書と同じ場所に残す（次の版で文言だけ直せる）。

### ラスタ画像の画風 spec（B2 ビジネスフラット高密度 — 文書内で固定）

ラスタ採用を確定したら、アクセント色（§8）を Phase 3 の生成前に前倒しで確定し、spec に埋め込む（Phase 4 を待つと図と本文の色が揃わない）。複数枚は 1 回の `codex exec` にまとめる（分けるとスタイル統一が壊れる）。共有 STYLE spec は再走時も変えない。

**spec の前に、描く内容（題字／各ゾーンの要素と数値／下段の要点3〜4個／決め数値1個）を全文字列で列挙してから**、以下を続けて渡す:

```
横16:9 の日本語ビジネス図解インフォグラフィック。背景は画面全域を純白 #FFFFFF にする。
手描き感のない、輪郭が均質でエッジの立ったフラットベクター描画（角丸長方形・幾何学的ピクトグラム・
直線とエルボーの矢印。線幅は全図で統一）。配色はダークグレー #1f2937（線・本文）＋アクセント1色
<確定した accent 値> ＋薄グレー #eeeeee の塗りのみ。
構図は縦3ゾーン:
(1) 最上段に結論を言い切る題字1行（20字以内）。
(2) 中段（面積の約6割）は対比または構造の本体。Before/After 型なら左右または上下に2分割し、
    Before 見出し帯は濃灰・After 見出し帯はアクセント色。全ボックスに「名詞＋数値」の副ラベルを
    付ける（例: 要約系 4回）。処理の反復は同一アイコンをその個数分だけ実際に並べる（5回なら5個描く）。
    読み順は丸数字①②③…で明示。流れの終端には必ず ✗（問題・未達）か ✓（解決・到達）を置く。
    設定値・パス・コマンド等の実データ文字列は monospace 風で一字一句正確に描き、強調は該当部分
    だけをアクセント色の点線枠で囲む。問題点は短い吹き出しで注釈する。
(3) 下段は要点3〜4連ボックス帯（各=小アイコン＋10字以内の短文）。Before/After 型なら「課題」「改善」
    の対見出しを付ける。決め数値が1つあれば右下にアクセント色の枠バッジで最大級に描く（例: −51%）。
    決め数値のない題材では省略してよい。
アイコンはダークグレー＋アクセント色の2色フラットピクトグラム。影・立体感なし。
文字: すべて日本語（技術固有名詞の英字は可）。最小文字サイズは画像高の 1/45 以上。
冒頭で列挙した文字列以外のテキストを描かない。誤字・存在しない漢字を作らない。
禁止事項: クリーム色・生成り・ベージュ・和紙テクスチャの背景は禁止（背景は必ず純白 #FFFFFF）。
手描き風の線の揺れ・ラフスケッチ調・鉛筆テクスチャ禁止。グラデーション・ドロップシャドウ・3D・
写実表現禁止。アクセント色は1色のみ（2色目のアクセント禁止。ただし超過・未達を示す1要素に限り
警告色 #c2740a を使ってよい）。列挙にない英語の飾りテキスト
（Overview 等）を勝手に追加しない。余白だけの大きな領域を作らない。
```

密度の基準: 1枚に主張1つ＋それを支える根拠2〜3要素（下段の要点帯を含む）。詰め込みで縦に伸びるなら2枚に分ける。
一次情報の正本は本文/SVG 側に置く（図=入口、本文=記録）。厳密文字の網羅が図の骨子そのものである図（構成図・ER・実パス一覧）は引き続き drawio か SVG。

### ラスタ画像の生成手順（marker 検証つき）

codex-imagegen スキルの標準実行コマンド（`env -u OPENAI_API_KEY codex exec` によるサブスク枠生成 + Claude 側コピー）に倣い、偽装防止の marker 検証を必ず行う:

```bash
# Step 0: 偽装検証用の開始マーカー
touch /tmp/bizdoc-imagegen-start.marker

# Step 1: 生成（プロンプトは内容+テイスト+品質バーのみ渡し、レイアウトは委譲する）
env -u OPENAI_API_KEY codex exec --skip-git-repo-check -C "$(pwd)" \
  -c model_reasoning_effort=high \
  -o /tmp/bizdoc-imagegen-last.txt \
  '<プロンプト本文> 画像は必ず image_gen ツールで生成すること。SVG/HTML/コードでの自作や既存ファイルの流用は禁止。失敗時は何も作らず IMAGEGEN-UNAVAILABLE とだけ報告して終了。生成後、保存された最終PNGの絶対パスだけを最後に1行で報告して。 $imagegen'

# Step 2: マーカーより新しい実ファイルのみ採用（偽装・流用・失敗を弾く）
SRC=$(grep -oE "${HOME}/.+/generated_images/[^ ]+\.png" /tmp/bizdoc-imagegen-last.txt | tail -1)
if [ -n "$SRC" ] && [ -n "$(find "$SRC" -newer /tmp/bizdoc-imagegen-start.marker 2>/dev/null)" ]; then
  cp "$SRC" "<保存先の一時ディレクトリ>/<kebab-name>.png"
else
  echo "警告: image_gen 未実行の疑い（偽装/流用/失敗）— コピー中止、同じプロンプトで再実行する"
fi
```

検証に落ちた画像は文書に使わない。コピー後は Read で目視し、文字化け・情報の薄さがないか確認する。

## 8. Phase 4: HTML 組立

`<head>` に **`<style data-bizdoc="tokens"></style>` とだけ書く**（中身は空のまま）。CSS 本体とアクセント色は Phase 5 の `hub.mjs add` が注入する — tokens.css を Read して手で書き写さない（毎文書 9,000 字超の出力を払うことになり、テンプレを直しても既存文書に反映できなくなる）。

スクラッチ段階のファイルは無スタイルで正しい。完成形になるのは hub に保存された後で、§2 の「1枚 HTML 縛り」は**保存物**について不変（保存後は外部参照ゼロの自己完結ファイル）。

### アクセント色の決め方

Phase 5 の `add` に **`--accent "#rrggbb"` を渡すだけ**でよい。判断は CLI 側が持つ:

- そのプロジェクトに既に accent があれば**既存値が優先**される（同一プロジェクトの文書間でぶれない）
- 未設定のときだけ `--accent` が採用され、`project.json` へ書き戻される
- `--accent-soft` は accent から決定論的に導出される（手で指定しない）

`project.json` を直接読み書きしたり、`reindex` を手で追加実行したりしない。

**未設定のプロジェクトでは、案件の色に寄せられないか一度だけ確かめる。** 既に accent があるときは
この手順を飛ばす（何を渡しても既存値が勝つので、走らせるだけ無駄になる）。未設定かどうかは
`list --json` の `accent` が `null` かで判定する — `#2563eb` が入っていれば既に確定済みで、対象外。

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/hub.mjs" list --json   # 対象プロジェクトの accent が null か見る
node "${CLAUDE_PLUGIN_ROOT}/scripts/accent-candidates.mjs" <プロジェクトルート> --limit 3
```

スタイル定義から候補色を集める。**このスクリプトは候補を出すだけで、色を決めない。**
実測（2026-08-31・社内5案件）で、変数名から自動選択させると 3 件中 1 件しか人の選択と一致せず、
和名の体系（`--shu` 朱 / `--ai` 藍）を持つ案件では色相が 76.8° ずれた。一方で除外は確実に効く —
hover 用の `--accent: 243 244 246`（gray-100）も本文色 `--text-primary` も、機械が落とす。

- **候補が出たら AskUserQuestion で1問だけ聞く**。第1選択肢を1位の候補にし、既定 `#2563eb` を残す
  選択肢も必ず添える。ラベルには色と変数名を出す（例:「#147b73（--teal / 対白 5.11:1）」）。
  AskUserQuestion の選択肢は**4つが上限**なので、`--limit 3` で候補を3件に絞り、4つ目を既定にする
- **候補が空なら聞かない**。既定のまま進めるか、トピックに合う色を渡す
- 候補は既にコントラスト 4.5:1 と `--warn` からの色相 45° を満たしている。**この2条件を外して
  独自に色を作らない** — v0.9.0 で警告色が入り、暖色の accent は「推奨」と「要検討」のバッジが
  判別できなくなる（tokens.css の `--warn` 節を参照）
- 聞くのは**そのプロジェクトの初回文書のときだけ**。2本目以降は write-once で自動的に黙る

### 組み立て

`outline.json` の `cover` → `.cover`、`exec_summary` → `.exec-summary`、`blocks` を順番どおりに `components.md` / `svg-patterns` のスニペットへ差し込んで本文を組み立てる。数値ブロックには `<p class="src">※ 出典: ...</p>` を必ず添える（Phase 1 で確認した出典）。ただし `※ 出典` 行は**セクションにつき原則1本、節末に集約**する。同一出典を要素ごとに繰り返さない（KPI カード内に個別出典行を置かず、グリッド直後に1本で束ねる）。

- 表紙は `.kicker`（種別）→ `h1`（メッセージ性のあるタイトル）→ `.lede`（2文以内の機能記述。広告コピー調にしない）→ `.meta`（日付・読者・種別など）の定型で組む
- 図は `<figure>` + `<figcaption>` で包む（枠と「図N」採番は tokens.css が自動付与）。**figcaption は図と本文を繋ぐ1行のナレーション**にする — 図の主張を1文で言う（「売上推移」型の名詞ラベルは禁止。「値引き後もリピート率は上がっていない」のように言い切る）。本文は図中ラベルをそのままの語で主語に使い、言い換えない。SVG は `svg-patterns/README.md` 予防則9の規範（font-size 14.5 以上。viewBox 幅 780 以下なら無条件で合格し、超える場合は同項の式で実表示 14px 以上を確認する）に従う
- **コマンド・コード**: 複数行は `<pre><code>…</code></pre>` で包み、文中の識別子1個（`--scope local` 等）だけを `<code>` 単独で使う。`<pre>` 無しの `<code>` を複数行にまたがらせない（inline のチップ装飾が行ごとに分断される）。**長い行は手で改行を入れて折らない** — 横スクロールに任せる（コマンドは折ると貼り付けて動かなくなる）。HTML なので `<` `&` はエスケープする。コードブロックは器幅の視覚要素なので、密度規範では図・表と同じく1画面1つの枠として数える
- **目次**: `<section>` が **5個以上**なら `.exec-summary` の直後に `<nav class="toc">` を置く（4個以下は省略）。
  各 `<section>` に `id="s-01"` 形式（`h2` の採番と同じゼロパディング）の id を振り、`<a href="#s-01">` で飛ばす。
  **`.conclusion` は採番対象外**なので id も振らず目次にも載せない（h2 の番号と id を同じ規則で数える）。
- **セクション番号・図番号の機構（v0.11.1 / v0.11.2）**: 番号は tokens.css の CSS カウンタ（`section > h2 { counter-increment: sec }`）で付く。
  祖先に `counter-reset: sec` が無いと各 h2 がカウンタを新設して**全部「01」になる**。tokens.css は `body` でリセットするため
  `<main>` の有無に依存しない（`<main>` を書いてもよいが必須ではない）。図番号 `fig` も同じ body の 1 宣言（`counter-reset: fig sec`）でリセットする —
  別規則で重ね書きすると後勝ちで先の宣言が消える（v0.11.2 で直した「全部 図1」の原因）。終端の `.conclusion` は `<section class="conclusion">` /
  `<aside class="conclusion">` のどちらで書いても番号を消費しない。`hub.mjs add` は h2 の数と目次リンク数の不一致を stderr に warn する。
  目次項目は `h2` の全文ではなく **25字程度に要約した短縮形**を使う（メッセージ見出しはそのままでは2カラムに収まらない）。
  紙ではページ番号を持たないため tokens.css が印刷時に非表示にする — 画面用の地図として置く

```html
<nav class="toc">
  <h2>目次</h2>
  <ol>
    <li><a href="#s-01">費用増の原因は分析対象の拡大</a></li>
    <li><a href="#s-02">現状は1通話に最大9回の解析</a></li>
  </ol>
</nav>
```
- 末尾に `<footer>`（生成元・日付などの文書管理情報）を置く

本文・フッターに OS のユーザーホーム配下を指すフルパスや個人アカウント名を書かない（`~/` 表記か論理名を使う。題材がローカルファイルの場合も同様）。

組み立てた HTML はスクラッチ領域の一時ファイル（例: セッションのスクラッチディレクトリ、または `mktemp` で作った一時パス）に Write する。次の Phase でこのファイルパスを `hub.mjs add` に渡す。

## 9. Phase 5: hub 保存 + 検証

```bash
# 保存（SVG 検証→manifest→reindex まで CLI が実施。出力 = 保存先 index.html のパス）
node "${CLAUDE_PLUGIN_ROOT}/scripts/hub.mjs" add "<組み立てたHTML>" \
  --project "$(pwd)" --title "<タイトル>" --slug "<英語kebab-caseスラッグ>" \
  --type "<種別>" --tags "<a,b>" --accent "#rrggbb"

# 決定論ゲート2: 全体を 2000px ごとのセグメント PNG に分けて撮り、図・表を DOM 位置から切り出して 2 倍で書き出す
node "${CLAUDE_PLUGIN_ROOT}/scripts/screenshot.mjs" "<保存先index.html>" "<scratchpad>/shot"
```

- `<組み立てたHTML>` = Phase 4 でスクラッチ領域に書き出した一時ファイルのパス
- `<タイトル>` / `<英語kebab-caseスラッグ>` / `<種別>` / `<a,b>` = Phase 0/2 で確定した内容
- `hub.mjs add` は内部処理の最初に SVG の XML 妥当性を検証する（決定論ゲート1。stdout の1行目＝保存先パスのことではない）。不正な SVG があれば add がここで中止するので、Phase 3 のスニペットを見直す
- `add` は保存時に **tokens.css と hub ナビを注入する**。保存物のスクリーンショット上部に「← doc-hub 一覧」のバーが出るのは正常（hub 配下のパスでのみ表示され、メール添付などで持ち出したコピーでは自動的に消える。印刷にも出ない）。**tokens.css を更新しても保存済み文書には自動で届かない**（注入時の CSS が焼き込まれる）ので、テンプレートを直したら `hub.mjs retheme` で貼り直す（例: v0.11.2 の図番号修正）
- スクリーンショットが**無スタイル**（素の HTML に見える）なら、`<style data-bizdoc="tokens"></style>` を書き忘れているか、プラグインのキャッシュが古い
- 同じ slug のドキュメントが既にあると `add` は既定で停止する（勝手に上書きしない）。ユーザーの意図が更新なら `--update`、別ドキュメントとして残すなら `--new` を確認してから付ける
- `<scratchpad>/shot` = 一時的な出力ディレクトリ（`mktemp -d` 等）。`screenshot.mjs` は `full-NN.png`（全体を上から 2000px ごとに分割・幅 1280・等倍。Read が縮小せず本文が読める）と `crop-NN-<figure|table|div.kpi-grid>.png`（各図表を前後の本文 2 行分込みで 2 倍解像度に再ラスタライズ）を書き、stdout に JSON（`height`・`segments`・各 crop の `tag`/`top`/`height`/`truncated`/`skipped`）を返す。Chrome CLI の `--screenshot` は使わない（ビューポート分しか撮れず、実文書の大半が 4000px を超えるため下半分の図表が写らない。2026-09-03 実測 10/10 文書。1 枚撮りは 16384px 超で先頭の複製に化けるため分割する）
- JSON の `crops` の件数が文書内の図表の数（`figure` / `table` / 数値カードの `.kpi-grid`）と一致するか先に確かめる。0 件ならそれらの要素で組んでいない（`--selector` で対象を足せる）。`truncated: true`（高さ 2400px 超で先頭しか撮れていない）か `skipped: true` の crop が 1 件でもあれば、その要素は表を分割するか `--selector` で単独指定して撮り直してから判定する

セグメント PNG は骨格と位置の確認に使い、図表の判定は crop 側で行う。**目視の印象ではなく数えて**確認する項目:

全体 PNG（`full-NN.png` を順に Read する。文字を読む検査は保存 HTML への `grep` と併用する）で:
- **本文1行の文字数が 45字を超えていないか** — 超えていれば `--measure`（tokens.css）が効いていない
  （`section > p` 等に当たっているか、`<p>` が `<section>` の直下にあるかを確認する）。
  `.callout` / `.callout-warn` と `.exec-summary` / `.conclusion` のパネル内テキストは器幅で組む
  視覚要素なので**この検査の対象外**（約60字/行が正常）。代わりに**囲みの本文が4行以内か**を数える
- **骨格検査**: 見出し＋sec-lede だけを拾い読みし、(a) 論旨が再構成できるか、(b) 全見出しが「答えの言い切り」で完結して読む理由が消えていないか（未解決要素が残っているか）を確認する
- **見出しの構文検査（v0.9.0）**: 見出しを縦に並べ、同一構文が3節連続していないか数える。連続していれば §6「構文を散らす」に戻り、1つを疑問形か機能ラベルへ替える
- **言葉づかいの検査（v0.9.0）**: §6「言葉づかいの規範」を1度通す。特に (a) 同じ節で見出し・lede・callout が同じ主張を3回言っていないか、(b) 「大幅に」「適切に」など具体へ落とせる抽象語が残っていないか、(c) 実装側の呼称が本文の主語になっていないか
- **警告色の検査（v0.9.0）**: `--warn` / `.callout-warn` / `tr.warn` / `.tag-warn` の使用箇所を数え、意味が「超過・未達・停止・要対処」に限られているか、1図につき1要素までかを確認する
- **前方参照検査**: 保存 HTML に `grep -nE '後述|（[0-9０-９]+ ?章）|別紙'` を実行し、根拠が参照だけのセル・本文が残っていないか確認する（残っていれば §6 の前方参照禁止に戻る）
- **番号が通し採番になっているか（v0.11.2）** — セクション番号 `01, 02, 03 …` と図番号 `図1, 図2 …` を上から数える。全部 `01` / 全部 `図1` なら tokens.css のカウンタリセットが効いていない（`counter-reset` の重複宣言か、tokens 未注入）
- **コードブロックが行ごとの角丸チップに割れていないか** — 割れていれば `<pre>` で包み忘れている（`<code>` 単独で複数行を囲っている）

図表の crop PNG（`crop-NN-*.png`。1 枚ずつ Read する）で:
- **表のセルが3行以上に折り返していないか** — 折り返していれば §6 の配置規範（1セル40字以内・4列以内）に
  戻り、長文セルを本文か `.card` へ移す
- **図中テキストの実表示サイズ** — crop には前後の本文が含まれているので、図中文字が本文と同等以上の大きさで読めるか・複数の図の間で文字サイズが揃っているかを本文と並べて比べる。viewBox 幅が figure の実幅（W=918px）より大きい SVG は縮小表示される（縮小率の高い図は viewBox 座標系の font-size を上げる。svg-patterns/README.md 予防則9）。数値で先に当たりを付けるなら、実表示サイズ ≒ font-size × 918 ÷ viewBox 幅
- **文字化け・アクセント色の破綻・はみ出し**

崩れがあれば HTML を修正し、`--update` を付けて `add` を再実行する。再保存後は再度 `screenshot.mjs` → Read の確認を、崩れがなくなるまで繰り返す（修正後の再検証なしで完了しない）。この検品は Phase 5 のスクリーンショットに限る（PDF は §10 の手順で目視する）。最後に保存先を `open` し、doc-hub 全体の一覧（`node "${CLAUDE_PLUGIN_ROOT}/scripts/hub.mjs" open --project "$(pwd)"` で開ける）の場所をユーザーに案内する。

## 10. Phase 6: PDF（要求時のみ）

「PDF でも」「配布用に」と言われたときだけ実行する。

```bash
# 主経路: 全ページに「文書タイトル ｜ ページ番号/総ページ」フッター付きの A4 PDF
node "${CLAUDE_PLUGIN_ROOT}/scripts/print-pdf.mjs" \
  "<保存先index.html>" "$HOME/Downloads/<slug>.pdf" --title "<タイトル>"
```

印刷レイアウトは画面より高密度になる（tokens.css の `@media print` が余白・行間・部品を圧縮する）。ページ数をさらに絞りたい要望があれば `--scale 0.9` を付けて全体を縮小できる（既定 1）。

Chrome が既定パスにない等で主経路が失敗したときだけ、フォールバック（ページ番号なし）を使う:

```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \
  --print-to-pdf="$HOME/Downloads/<slug>.pdf" --no-pdf-header-footer \
  --virtual-time-budget=20000 "file://<保存先index.html>"
```

（フォールバックでは `--no-pdf-header-footer` を必ず付ける — Chrome 既定のフッターは file:// のフルパスを印字してしまい path-privacy 違反になる）

書き出し後は Read で**先頭・中間・末尾ページ**を目視し、次を確認する:
- フッターのタイトル・ページ番号が全ページに入っているか（主経路）
- 図・表・カードが不自然に分断されていないか（長い表は行単位で改ページし、ヘッダ行が次ページに繰り返されるのは正常）
- 白基調の面色（exec-summary・表ヘッダ等）が抜けていないか・日本語の文字化けがないか
- **図送りによる大きな余白が出ていないか** — 図はページ残量に入らないと丸ごと次ページへ送られ、直前に余白が生まれる。目立つ場合は組版調整を行う: 図の直前の段落を図の後ろへ移す／該当セクションに `.page-break` を付けて頭出しする／図が viewBox 高さ 500 超なら2枚に分割する（予防則10）。調整したら `--update` で再保存し、PDF を再書き出しして再確認する

PDF は一時配布物なので manifest に記録しない（`hub.mjs add` を再実行しない）。ラスタ画像（codex-imagegen 生成分）を使った文書は、そのまま書き出すと容量が膨らむため、印刷用の一時コピーを作って画像だけ軽量化してから書き出す（元の HTML・保存済みドキュメントは変更しない）。書き出し後は Read で先頭数ページを目視し、分断・色抜け・文字化けがないか確認する。

## 11. Gotchas

- **図番号が全部「図1」になったら tokens.css を疑う** — body の `counter-reset` は `fig sec` を 1 つの宣言に持つこと。v0.11.1 は `fig` と `sec` を別の宣言に分けたため後の宣言が前を消し、全図が 図1 になった（v0.11.2 で修正、tests/figure-numbering.test.mjs が固定）
- **draw.io の SVG を自前で整形しない** — id の付け替え・色固定・幅の除去は `drawio-bridge` の `inline` に任せる。手動の正規表現置換は `style` 属性内の `url("#…")` を取りこぼし、AWS アイコンのタイルが消える（2026-09 実測）
- **同じ slug の再生成は勝手に上書きしない** — `hub.mjs add` が既定で停止する。ユーザーに更新意図を確認してから `--update`（別ドキュメントとして残すなら `--new`）を付ける
- **見出しの「言い切り完結」も仕上げ段階で直す** — 目次と見出しだけ読んで疑問が1つも残らなければ、本文は読まれない。§6 の「未解決要素を1つ残す」検査に戻る
- **見出しのトピックラベル化は仕上げ段階でも直す** — Phase 5 の PNG 確認時に見出しだけを拾い読みし、主張の文が並んでいなければ Phase 2 の構成規範に戻って書き直す
- **アクセントは1色のみ** — 複数のアクセント色を併用しない（tokens.css の `--accent` を1つだけ振る）。**唯一の例外が `--warn`**（v0.9.0）で、超過・未達・停止・要対処にだけ使う。良好・情報を示す色は作らない（信号機にしない）。**accent が橙〜赤褐色のプロジェクトでは warn（色相 34.6°）と近接する**（テラコッタ #A6472B で 20.9°・橙 #ea580c で 14.0°）ので、同一画面に両方を並べない
- **図=入口、本文=記録** — 構造を主張する節は図を節頭（sec-lede 直後）に置き、本文は図中ラベルの語をそのまま主語に使って図を歩く。ただし要点が図にしかない状態は禁止（本文が正式な記録。検索・選択・読み上げの正本は本文）
- **表に長文を詰めない** — 表は本文より広いが列で割られるため、1セル40字超は必ず3行以上に折り返して読み物化する。
  A/B 実測で「bizdoc は難しい」と評された主因のひとつだった（explainer 側は td 最長35字・40字超ゼロ、
  bizdoc 側は最長75字・40字超5個）。表は一覧して比べる道具であり、読ませる器ではない
- **数字に出典なし断定禁止** — Phase 1 で出典が確認できなかった数字は「未確認」と明記し、`<p class="src">` を省略しない
- **SVG の入れ子禁止** — hub の SVG 検証（xmllint 経由）が入れ子に対応しない。1文書内で `<svg>` は並列に配置する
- **SVG は必ずインライン** — `<img src="pattern.svg">` にすると `var(--accent)` 等の CSS 変数が解決できず無色・黒塗りになる
- **project.json の accent は既存値があれば上書きしない** — 同一プロジェクトの文書間でアクセントがぶれるのを防ぐ
- **codex-imagegen の marker 検証を省略しない** — 省略すると偽装・流用画像をそのまま納品してしまう
- **PDF の紙面余白は目視でなく実測で確かめる** — Chrome の `Page.printToPDF` は、文書が `@page` の margin を明示していると CDP の `margin*` パラメータを**無視して CSS 側を優先する**。かつて print-pdf.mjs は「二重適用を避ける」つもりで `@media print{@page{margin:0}}` を注入しており、それが勝って余白が完全に消えていた（2026-08-07 実測で左右 0.0mm）。現在は同スクリプトの `MARGIN_*_MM` を唯一の正とし、`@page` への注入と CDP の両方をそこから導出している。余白を変えるときは必ずこの定数を触り、書き出し後に実測する:
  ```bash
  python3 -c "
  import fitz; d=fitz.open('<out.pdf>'); mm=25.4/72; p=d[0]; r=p.rect
  bb=None
  for g in p.get_drawings(): bb = g['rect'] if bb is None else bb | g['rect']
  print(f'L{bb.x0*mm:.1f} R{(r.width-bb.x1)*mm:.1f} T{bb.y0*mm:.1f} B{(r.height-bb.y1)*mm:.1f} mm')"
  ```
  ページ画像の目視ではこの種の欠落を見落とす（本文が紙面いっぱいでも「そういうデザイン」に見えてしまう）
- **スキルを直したら `version` を上げる** — プラグインキャッシュ（`~/.claude/plugins/cache/`）は version が変わらないと再取得されない。配布元リポジトリだけ直してもセッションには反映されず、「直したつもりで直っていない」状態になる（上記の余白バグは、値だけ 15mm に修正済みなのにキャッシュが 13mm のまま、かつ根本原因も残っていた実例）