explainer

# explainer 人間の理解がボトルネックになっている。 エージェントは書くのが速いが、読み手は追いつけない。 このスキルは、**読み手の頭の中にあるものとの差分だけ**を、**検証済みの主張と図**で渡す。 ELI5 との違いは 2 つ。 1. 読み手を「5 歳」「マネージャー」のような型でなく、**実在の 1 人のペルソナ**として持つ。知っていることは書かない。 2. 書いた主張を**道具で検査する**。「自分で書いていて自信がなくなる」を、検査の緑に置き換える。 読了が 20 分を超える、演習が要る、概念に順序がある。このどれかなら、章立ての `explainer-book` を使う。 ## 準備（初回だけ） スクリプトは、このスキルのディレクトリ（以下 `<skill>`）の `scripts/` にあります。 依存は、資料を置くリポジトリに入れます。Node 24 以上が必要です。 ```sh npm i -D @mizchi/vlmkit @mizchi/vlmkit-anim marked playwright ``` Mermaid の図（`figures/*.mmd`）を使うときは `mermaid`、アイコンを使うときは `@iconify-json/lucide` と `@iconify-json/logos` も入れます。 形式手法の例を扱うときは、TLC（Java 11+）や Apalache（Java 17+）、`z3-solver` も入れます。 `verify-doc.mjs` は `$TLA2TOOLS`（tla2tools.jar）と `$APALACHE`（apalache-mc）を、リポジトリの `.tools/` から探します。 ## 手順 ``` 1. ペルソナ リポジトリのルートの personas/<id>.md を読む。無ければ、質問する前に仮のファイルを書く 2. 問いを絞る 読み手が「読み終えたら判定できるようになること」を 1〜3 個、疑問文で書く。伝えたいこと 1 文と、節ごとの役割の表を書く前に作る 3. 差分を決める ペルソナの「知っている」に載っていることは書かない。「怪しい」を本文の芯にする 4. 実物を作る 主張ごとに、実行できる例（コード・モデル・コマンド）を先に作って走らせる 5. 書く references/writing.md の型で。価値を先に、根拠は後に。出力は貼る、打ち直さない。書き終えたら削除テスト 6. 図 references/figures.md。事実シート（*.expect.json）を先に、図は後 7. 検証 node <skill>/scripts/verify-doc.mjs <doc-dir> が VERIFIED になるまで 8. 読ませる first-reader スキルで、ペルソナ本人を読み手にして読ませる。途中で離脱した箇所と、翌日残ったものを見る 9. 渡す HTML（dist/index.html）と要約。検証できなかったことは「未検証」と明記 ``` ### 1. ペルソナ `references/persona.md` のテンプレートで作る。材料は 2 つ。 - **質問**：本人に聞けるなら、最大 5 問。「いま何を使っているか」「どこで手が止まったか」「読む時間」「好きな説明の形（コード先か図先か）」「この資料を読んだ後に何を判定したいか」。 - **公開情報**：GitHub のリポジトリ、ブログ、登壇資料。主張ごとに URL を付け、**事実と推測を分けて書く**。 **ペルソナのファイルは、答えを待つ前に書く。** 新しい読み手なら、質問する前に、リポジトリのルートの `personas/<id>.md` を作る（資料のディレクトリの中ではない。次の資料でも使い直すため）。 質問して止まる返答でも、このファイルは先に書いておく。 依頼文から分かったことは「事実」に、それ以外はすべて「推測」に書き、質問は「未確認」の欄に並べる。 - 本人に聞けるときは、質問して止まる。答えが来たら、ファイルの推測を事実に書き換えて続ける。 - 答えが得られないとき（非対話の実行、本人に聞けない、急ぎ）は、推測のまま書き進める。 資料の冒頭の「想定読者」に、何を仮定したかと、確かめたい質問を書く。 - 依頼文にない経歴（経験年数、使っているツール、困りごと）を事実の欄に書かない。 **推測は答えではない。** 依頼文に書かれていないことは、どれほどもっともらしくても「推測した」に置き、理由を添える。 読み手について返答するときは、毎回この 2 つを分けて見せる。黙って決めない（非対話の実行でも同じ）。 新しい読み手に質問して止まるときの返答は、次の型にする。 **返答を書く前に**、Write で `personas/<id>.md` を作っておく（ツールを呼ばずに質問だけ返さない）。 ``` <読み手> さんの仮のペルソナを personas/<id>.md に残しました。 依頼文にあった：<依頼文から分かったことだけ> 推測した：<推測>（理由：<なぜそう置いたか>） 書く予定の資料：この資料は <読み手> に <伝えたいこと> を伝える。構成は 1. <節の役割> 2. … 3. … 資料の中身が変わる点を <N> つ確認させてください。 1. <答えで資料の主軸が変わる質問> 2. … 答えがなければ、「推測した」のまま書き進めます。 ``` 推測のまま資料を書き進めたときの返答は、冒頭を次の型に固定する。ファイルにだけ書くと、読み手に届かない。 順番も変えない。2 行目は必ず「伝えたいこと」。「未検証」などの注意は、この型の後に書く。 ``` <path> を書きました（<読み手> さん向け。仮のペルソナは personas/<id>.md）。 伝えたいこと：この資料は <読み手> に <伝えたいこと> を伝える。構成は 1. <節の役割> 2. … 3. … 依頼文にあった：<依頼文から分かったことだけ> 推測した：<何を知っている前提にしたか>（理由：<なぜそう置いたか>） 確かめたいこと：1. <答えで資料の主軸が変わる質問> / 2. … （ここから後に：未検証の点、手元で確かめる手順） ``` 資料を作らず、チャットで説明するとき（PR の説明など）も、冒頭は同じ型にする。 ``` この説明は <読み手> に <伝えたいこと> を伝える。 依頼文にあった：… / 推測した：…（理由：…） 構成：1. <何が変わるか（価値）> 2. <根拠：差分・例> 3. <確かめてほしいこと> ``` 依頼文の言い換えを、本人の言葉のように書かない（「田中さんの問い『…』」ではなく、「依頼文から、問いを『…』と置いた（推測）」と書く）。 一番大事な欄は「怪しいところ」。 ツールを使えることと、その結果の意味を判定できることは別。 その差を見つけて、資料の芯にする。 ### 2〜3. 問いと差分 資料のタイトルは、読み手の問いの形にする（例：「Z3 と TLA+ の OK は何を保証したのか」）。 書く前に、伝えたいことを 1 文にし、節ごとの役割の表を作る。 ``` この資料は <読み手> に <伝えたいこと> を伝える。 | 節 | 役割（この節で言うこと 1 文） | 見せるもの（例・図・出力） | なぜ（伝えたいことにどうつながるか） | ``` - 「なぜ」が伝えたいことにつながらない行は、節ごと削る。 - 1 文と表は、資料の冒頭（想定読者の次）に置く。チャットで説明するときも、最初にこの 1 文と、節の並びを短く示す。 - 読み手が構成を先に見たいと言ったとき、または本（`explainer-book`）にするときは、表を見せて確認を取ってから書く。直すのは、読み手が名指しした行だけ。それ以外は、表を冒頭に置いて書き進める。 冗長さの判定は 1 つ。 **ペルソナの「知っている」欄にある説明は削る。** ツールの紹介、インストール手順、一般論は、ペルソナが既に使っているなら書かない。 ### 4. 実物を先に作る 主張は、走らせた結果から書く。逆にしない。 - コードの振る舞い → 最小の実行例と、その出力 - 「この条件で壊れる」 → 反例を出すモデル（Z3 / TLC など）と、反例を実物で再生するテスト - 構造 → import グラフや状態グラフを道具から出力し、それを事実シートにする 主張を実行で確かめられない場合は、本文に「未検証」と書く。図には入れない。 ### 5. 書く `references/writing.md` に従う。要点は次のとおり。 - 冒頭に「想定読者」と「省いたもの」を書く。読み手が自分向けかを 10 秒で判定できるように。 - 最初に「一枚で」の表を置く。本文はその表の各行の展開。 - 1 段落は 1〜2 文。1 節に例は 1 つ。 - 出力の引用は `<!-- output: <check名> -->`、コードの抜粋は `<!-- source: <path> -->` を直前に置く。検証スクリプトが実物と照合する。 - 末尾に理解度チェック（3〜5 問、答えは `<details>`）。読み手が答えられなければ、その節は伝わっていない。 ### 6. 図 `references/figures.md`。図を描くのは次の場合だけ。 - 4 つ以上の要素とその関係があるとき - 時間の順序があるとき - 包含関係があるとき 図は vlmkit-anim のシーン（JSON）で描く。当てはまる kind が無い概念図は、Mermaid で済むなら Mermaid、足りない構造なら D2、D2 に乗らない自由な図なら SVG / HTML で直接書く。どれも `scripts/figure-check.mjs` で描画・検査して、出てきたシートと辺のシート（矢印を 1 本ずつ強調したもの）を目で見て直す。D2 と Mermaid は配置を道具が決めるので、不自然なら `scripts/figure-variants.mjs` で候補を並べて選び直す（`references/figures.md` の「手で描く図」）。 アイコン（データベース・サーバ・製品のロゴなど）は `scripts/icons.mjs` で探して図の隣に置き、D2・Mermaid・SVG のどれからでも使う（`references/figures.md` の「アイコン」）。 vlmkit-anim の図の検査は 3 つ。 - `check --expect`：事実シートと照合する。事実シートは道具の出力（TLC の状態グラフ、import グラフ）から作る。 - `layout`：重なりやはみ出しがないか。 - `still`：SVG を出して、一度は目で見る。 ### 7. 検証 `<doc-dir>/checks.json` に、本文が引用する出力を再生成するコマンドと、期待する行を書く。 ``` node <skill>/scripts/verify-doc.mjs <doc-dir> # 検査 node <skill>/scripts/verify-doc.mjs <doc-dir> --write # 図の SVG を描き直す ``` `verify-doc.mjs` が見るもの： 1. `checks.json` の各コマンドの出力に、期待する行が順に出るか 2. 図：`vlmkit-anim check --expect` / `layout` / SVG が最新か 3. 本文：`output` / `source` の引用が実物と一致するか。画像が存在するか 4. HTML：`vlmkit check integrity`（`<details>` を開いた版で厳格に）と `check a11y contrast` 落ちた行は「何が・どこで・どう直すか」を 1 行で出す。 直して再実行し、`verdict: VERIFIED` になるまで繰り返す。 上限は 5 ラウンド。それでも通らない主張は本文から外すか、「未検証」と明記する。 ### 8. 読ませる（first-reader） `verify-doc.mjs` が保証するのは、主張が**正しい**ことだけです。 読み手が**最後まで読み、翌日も覚えている**かは、同梱の `first-reader` スキルで確かめる。 - **読み手の配役**： - sympathetic 役：`personas/<id>.md` の本人。「既に知っていること」を priors に、「読み方」を patience budget にする。 - skeptical 役：資料が届く場面（PR のレビュー、Slack のリンク）から配役する。 - **intended gist**：資料の「一枚で」の表と、ペルソナの問い（手順 2）。 - **判定**： - recall の答えが intended gist と食い違ったら、その節は伝わっていない。 - skim gate を通らない、または前半で両者が離脱したら、構成の問題として扱う。行単位の手直しより先に直す。 - **直すのは書き手（このスキル）**： - first-reader は書き直さない。読み手の証言を受けて、どこをどう直すかは explainer が決める。 - 直したら `verify-doc.mjs` を再実行し、first-reader は `again` で同じ読み手に読ませ直す。 - **注意**： - 書き手は下書きを全部読んでいる。読み手は必ず fresh な subagent にする（first-reader の手順どおり）。 - `signals.py` の信頼シグナルの数え方は英語向けで、日本語の資料ではほぼ 0 になる。日本語では trust ledger を自分の通読で判断する。 - `.first-reader/` は資料の隣に作られる。git 管理しない。 ### 9. 渡す - チャットでは、要約（3〜5 行）と `dist/index.html` を渡す。検証の結果（VERIFIED か、何が未検証か）も添える。 - PR では、差分の説明を同じ型で書き、図の SVG を添付する。理解度チェックは PR 本文の末尾に置く。 ## PR の説明に使うとき 問いは「この PR がマージされたら、何が変わるか」「何が壊れうるか」にする。 **価値を先に、根拠は後に。** 読み手（や利用者）にとって何が変わるかを、最初の 2 段落（2 節）までに書く。差分と仕組みは、その主張の根拠として後に置く。 差分はファイル順ではなく、説明の順に並べる（literate diff）。 実物は次の 2 つ。 - `vlmkit-anim pr --base origin/main` の変更地図 - 変更前後で振る舞いが変わる最小の例（テストの追加・変更から選ぶ） ## やってはいけないこと - **出力を打ち直す。** 貼る。検証スクリプトが照合する。 - **図を記憶から描く。** 事実シートを先に作る。図が事実シートと食い違ったら、図が間違っている。 - **読み手の既知を説明する。** ペルソナの「知っている」にあるものは削る。 - **緑を過大に報告する。** 「検査が通った」と書くときは、何の検査が、どの範囲で通ったかを書く。 ## ファイル | パス | 内容 | |---|---| | `references/persona.md` | ペルソナのテンプレートと、作り方 | | `references/writing.md` | 資料の型、文体、理解度チェックの作り方 | | `references/figures.md` | 問い → 図の種類の対応、事実シートの作り方、vlmkit-anim の手順 | | `scripts/verify-doc.mjs` | 検証（checks / 図 / 引用 / HTML） | | `scripts/build-html.mjs` | README.md → 自己完結 HTML（SVG をインラインで埋め込む） | | `scripts/figure-check.mjs` | 手で書いた SVG / HTML / D2 / Mermaid の図を描画し、重なり・はみ出し・枠線や線と文字の交差・小さすぎる文字・事実シートを検査し、目で見るシートを作る | | `scripts/figure-arrows.mjs` | 矢印の読みやすさ（2 本が重なって走る・箱を突き抜ける・交差・遠回り・逆向き）と、辺を 1 本ずつ強調したシート。figure-check が使う | | `scripts/figure-variants.mjs` | D2 / Mermaid の配置の候補（TALA の seed・ELK・dagre、向き）を描き、点数つきで並べる | | `scripts/icons.mjs` | Iconify のアイコンセット（lucide・logos）からアイコンを探し、候補を 1 枚に並べ、図の隣に置いて出典を ICONS.md に残す | | `scripts/tlc-to-scene.mjs` | TLC の状態グラフと反例 → vlmkit-anim の state-machine シーンと事実シート |