explainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

explainer

人間の理解がボトルネックになっている。エージェントは書くのが速いが、読み手は追いつけない。このスキルは、読み手の頭の中にあるものとの差分だけを、検証済みの主張と図で渡す。

ELI5 との違いは 2 つ。

読み手を「5 歳」「マネージャー」のような型でなく、実在の 1 人のペルソナとして持つ。知っていることは書かない。
書いた主張を道具で検査する。「自分で書いていて自信がなくなる」を、検査の緑に置き換える。

読了が 20 分を超える、演習が要る、概念に順序がある。このどれかなら、章立ての

explainer-book

を使う。

Human understanding is the bottleneck. Agents write quickly, but readers cannot keep up. This skill delivers only the delta relative to what is already in the reader's head, through verified claims and diagrams.

There are two differences from ELI5.

Treat the reader as one real persona, not a type such as “5-year-old” or “manager”. Do not write about what they already know.
Check claims with tools. Replace “I wrote this myself and no longer feel confident about it” with the green light from a passing check.

If reading takes more than 20 minutes, exercises are required, or concepts have a sequence, use the

explainer-book

chapter structure.

準備（初回だけ）

Preparation (first time only)

スクリプトは、このスキルのディレクトリ（以下

<skill>

）の

scripts/

にあります。依存は、資料を置くリポジトリに入れます。Node 24 以上が必要です。

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/

から探します。

The scripts are in this skill's directory (referred to below as

<skill>

), under

scripts/

. Install the dependencies in the repository where the material will live. Node 24 or later is required.

npm i -D @mizchi/vlmkit @mizchi/vlmkit-anim marked playwright

When using Mermaid diagrams (

figures/*.mmd

), also install

mermaid

. When using icons, also install

@iconify-json/lucide

and

@iconify-json/logos

. When covering examples of formal methods, also install TLC (Java 11+), Apalache (Java 17+), and

z3-solver

verify-doc.mjs

looks for

$TLA2TOOLS

(

tla2tools.jar

) and

$APALACHE

(

apalache-mc

) in the repository's

.tools/

directory.

手順

Procedure

1. ペルソナ   リポジトリのルートの personas/<id>.md を読む。無ければ、質問する前に仮のファイルを書く
2. 問いを絞る  読み手が「読み終えたら判定できるようになること」を 1〜3 個、疑問文で書く
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. Persona      Read personas/<id>.md at the repository root. If it does not exist, create a provisional file before asking questions
2. Narrow the question  Write 1–3 questions describing what the reader should be able to determine after finishing
3. Determine the delta  Do not write anything listed under the persona's “Knows”. Center the body on the “Unsure” items
4. Build real artifacts  For every claim, first create and run an executable example (code, model, or command)
5. Write  Follow the pattern in references/writing.md. Paste outputs; do not retype them
6. Diagrams  Follow references/figures.md. Create the fact sheet (*.expect.json) first and the diagram second
7. Verify  Run node <skill>/scripts/verify-doc.mjs <doc-dir> until the result is VERIFIED
8. Reader test  Use the first-reader skill with the persona as the reader. See where they drop off and what remains the next day
9. Deliver  Provide the HTML (dist/index.html) and a summary. Mark anything that could not be verified as “Unverified”

1. ペルソナ

1. Persona

references/persona.md

のテンプレートで作る。材料は 2 つ。

質問：本人に聞けるなら、最大 5 問。「いま何を使っているか」「どこで手が止まったか」「読む時間」「好きな説明の形（コード先か図先か）」「この資料を読んだ後に何を判定したいか」。
公開情報：GitHub のリポジトリ、ブログ、登壇資料。主張ごとに URL を付け、事実と推測を分けて書く。

ペルソナのファイルは、答えを待つ前に書く。 新しい読み手なら、質問する前に、リポジトリのルートの

personas/<id>.md

を作る（資料のディレクトリの中ではない。次の資料でも使い直すため）。質問して止まる返答でも、このファイルは先に書いておく。依頼文から分かったことは「事実」に、それ以外はすべて「推測」に書き、質問は「未確認」の欄に並べる。

本人に聞けるときは、質問して止まる。答えが来たら、ファイルの推測を事実に書き換えて続ける。
答えが得られないとき（非対話の実行、本人に聞けない、急ぎ）は、推測のまま書き進める。資料の冒頭の「想定読者」に、何を仮定したかと、確かめたい質問を書く。
依頼文にない経歴（経験年数、使っているツール、困りごと）を事実の欄に書かない。

新しい読み手に質問して止まるときの返答は、次の型にする。 返答を書く前に、Write で

personas/<id>.md

を作っておく（ツールを呼ばずに質問だけ返さない）。

<読み手> さんのペルソナを、仮のものとして personas/<id>.md に残しました（依頼文から分かったことだけを事実に、残りは推測）。
資料の中身が変わる点を <N> つ確認させてください。

1. <答えで資料の主軸が変わる質問>
2. …

答えがなければ、次の仮定で書き進めます：<仮定を 1〜2 行>

推測のまま資料を書き進めたときも、返答に同じ 2 つ（仮定と、本人に確かめたい質問）を短く書く。ファイルにだけ書くと、読み手に届かない。

一番大事な欄は「怪しいところ」。ツールを使えることと、その結果の意味を判定できることは別。その差を見つけて、資料の芯にする。

Create it using the template in

references/persona.md

. There are two sources of information.

Questions: If you can ask the person, ask up to five questions. “What are you using now?” “Where did you get stuck?” “How much time do you have to read?” “What form of explanation do you prefer (code first or diagrams first)?” “What do you want to determine after reading this?”
Public information: GitHub repositories, blogs, and conference presentations. Attach a URL to every claim and separate facts from inferences.

The persona file must be written before waiting for an answer. For a new reader, create

personas/<id>.md

at the repository root before asking any questions—not inside the material's directory, so it can be reused for future material. Even if asking a question pauses the response, create the file first. Write everything established by the request under “Facts,” everything else under “Inferences,” and list the questions under “Unconfirmed.”

If you can ask the person, ask the questions and pause. When the answers arrive, rewrite the inferences in the file as facts and continue.
If no answer can be obtained—such as during a non-interactive run, when the person cannot be contacted, or when there is no time—continue with the inferences as they are. At the beginning of the material, state your assumptions and the questions you want to confirm under “Intended Reader.”
Do not put background information that is not in the request—such as years of experience, tools currently used, or the person's difficulties—under “Facts.”

When asking a new reader and pausing for their response, use the following format. Before writing the response, use Write to create

personas/<id>.md

; do not ask the questions without first invoking the tool.

<Reader>'s persona has been saved provisionally at personas/<id>.md (only facts established by the request were recorded as facts, and everything else as inferences).
Please confirm <N> points that could change the content of the material.

1. <Question whose answer could change the main focus of the material>
2. …

If there is no answer, I will proceed with the following assumptions: <assumption in 1–2 lines>

Even when proceeding on the basis of inferences, briefly include the same two items in the response: the assumptions and the questions for the person. If you only write them to the file, they will not reach the reader.

The most important field is “Unsure.” Being able to use a tool and being able to interpret the meaning of its result are different things. Find that difference and make it the core of the material.

2〜3. 問いと差分

2–3. Questions and the Delta

資料のタイトルは、読み手の問いの形にする（例：「Z3 と TLA+ の OK は何を保証したのか」）。

冗長さの判定は 1 つ。 ペルソナの「知っている」欄にある説明は削る。 ツールの紹介、インストール手順、一般論は、ペルソナが既に使っているなら書かない。

Give the material a title in the form of the reader's question, such as “What do OK results from Z3 and TLA+ actually guarantee?”

There is only one test for excessive length. Remove any explanation listed under the persona's “Knows” section. If the persona already uses the tool, do not include its introduction, installation instructions, or general theory.

4. 実物を先に作る

4. Build the Real Artifact First

主張は、走らせた結果から書く。逆にしない。

コードの振る舞い → 最小の実行例と、その出力
「この条件で壊れる」 → 反例を出すモデル（Z3 / TLC など）と、反例を実物で再生するテスト
構造 → import グラフや状態グラフを道具から出力し、それを事実シートにする

主張を実行で確かめられない場合は、本文に「未検証」と書く。図には入れない。

Write claims from the results of running something. Never do it in the other order.

Code behavior → the smallest runnable example and its output
“It breaks under this condition” → a model that produces a counterexample (Z3, TLC, etc.) and a test that reproduces that counterexample as a real artifact
Structure → an import graph or state graph emitted by a tool, which becomes the fact sheet

If a claim cannot be checked by execution, write “Unverified” in the body. Do not include it in a diagram.

5. 書く

5. Writing

references/writing.md

に従う。要点は次のとおり。

冒頭に「想定読者」と「省いたもの」を書く。読み手が自分向けかを 10 秒で判定できるように。
最初に「一枚で」の表を置く。本文はその表の各行の展開。
1 段落は 1〜2 文。1 節に例は 1 つ。
出力の引用は
```

```
、コードの抜粋は
```

```
を直前に置く。検証スクリプトが実物と照合する。
末尾に理解度チェック（3〜5 問、答えは
```
<details>
```
）。読み手が答えられなければ、その節は伝わっていない。

references/writing.md

. The main points are:

Begin with “Intended Reader” and “Omitted.” The reader should be able to determine in 10 seconds whether the material is for them.
Put an “At a Glance” table at the beginning. The body then expands each row of the table.
Keep each paragraph to one or two sentences and each section to one example.
Put
```

```
immediately before quoted output and
```

```
immediately before code excerpts. The validation script compares them with the real artifacts.
End with a comprehension check of three to five questions, with the answers in
```
<details>
```
. If the reader cannot answer, that section has not communicated its content.

6. 図

6. Diagrams

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 を出して、一度は目で見る。

references/figures.md

. Create a diagram only in these cases:

There are four or more elements and relationships between them
There is a temporal sequence
There is a containment relationship

Create diagrams as vlmkit-anim scenes (JSON). If there is no applicable kind for a conceptual diagram, use Mermaid if Mermaid is sufficient, D2 if more structure is needed, or write SVG / HTML directly for a free-form diagram that D2 cannot represent. Render and check each one with

scripts/figure-check.mjs

, then visually review the resulting sheet and edge sheet, with one arrow highlighted at a time. Because D2 and Mermaid determine the layout automatically, if the result looks unnatural, use

scripts/figure-variants.mjs

to compare candidates and choose again; see “Hand-drawn Diagrams” in

references/figures.md

. Use

scripts/icons.mjs

to find icons such as databases, servers, and product logos, and place them beside the diagram. Icons can be used with D2, Mermaid, or SVG. See “Icons” in

references/figures.md

There are three checks for a vlmkit-anim diagram.

```
check --expect
```
: Compare it with the fact sheet. The fact sheet is generated from tool output such as a TLC state graph or import graph.
```
layout
```
: Check for overlaps and overflow.
```
still
```
: Emit an SVG and inspect it visually once.

7. 検証

7. Verification

<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

が見るもの：

```
checks.json
```
の各コマンドの出力に、期待する行が順に出るか
図：
```
vlmkit-anim check --expect
```
/
```
layout
```
/ SVG が最新か
本文：
```
output
```
/
```
source
```
の引用が実物と一致するか。画像が存在するか

HTML：

vlmkit check integrity

（

<details>

を開いた版で厳格に）と

check a11y contrast

落ちた行は「何が・どこで・どう直すか」を 1 行で出す。直して再実行し、

verdict: VERIFIED

になるまで繰り返す。上限は 5 ラウンド。それでも通らない主張は本文から外すか、「未検証」と明記する。

<doc-dir>/checks.json

, define the commands that regenerate the outputs quoted in the body and the expected lines.

node <skill>/scripts/verify-doc.mjs <doc-dir>          # Check
node <skill>/scripts/verify-doc.mjs <doc-dir> --write  # Redraw the diagram SVGs

verify-doc.mjs

checks the following:

Whether the expected lines appear in order in the output of each command in
```
checks.json
```
Diagrams: whether
```
vlmkit-anim check --expect
```
,
```
layout
```
, and the SVG are up to date
Body content: whether quoted
```
output
```
and
```
source
```
content matches the real artifacts and whether images exist
HTML:
```
vlmkit check integrity
```
on the version with
```
<details>
```
expanded, using the strict mode, and
```
check a11y contrast
```

For each failed line, report what failed, where it failed, and how to fix it on one line. Fix the issue and rerun the checks until the verdict is

VERIFIED

. The limit is five rounds. If a claim still does not pass, remove it from the body or mark it as “Unverified.”

8. 読ませる（first-reader）

8. Reader Testing (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 管理しない。

What

verify-doc.mjs

guarantees is only that the claims are correct. Whether the reader can finish the material and still remember it the next day must be tested with the bundled

first-reader

skill.

Reader roles:
- Sympathetic role: the person in
```
personas/<id>.md
```
  . Use “Already Knows” as the priors and “How They Read” as the patience budget.
- Skeptical role: assign the role from the context in which the material will be delivered, such as a PR review or a link in Slack.
Intended gist: the material's “At a Glance” table and the persona's questions from step 2.
Judgment: If a recall answer differs from the intended gist, that section has not communicated its content. If the skim gate does not pass, or both readers drop out during the first half, treat it as a structural problem. Fix the structure before making line-level edits.
The writer (this skill) makes the fixes: first-reader does not rewrite the material. After receiving the reader's testimony, the explainer decides where and how to fix it. After making fixes, rerun
```
verify-doc.mjs
```
and use
```
again
```
in first-reader to have the same reader read it again.
Caution: The writer has already read the entire draft. The reader must always be a fresh subagent, following the first-reader procedure. The way
```
signals.py
```
counts trust signals is designed for English and will produce almost no signals for Japanese material. For Japanese, judge the trust ledger through your own read-through.
```
.first-reader/
```
is created next to the material. Do not manage it with Git.

9. 渡す

9. Delivery

チャットでは、要約（3〜5 行）と
```
dist/index.html
```
を渡す。検証の結果（VERIFIED か、何が未検証か）も添える。
PR では、差分の説明を同じ型で書き、図の SVG を添付する。理解度チェックは PR 本文の末尾に置く。

In chat, provide a three-to-five-line summary and
```
dist/index.html
```
. Also include the verification result: whether it is VERIFIED and what, if anything, remains unverified.
In a PR, describe the diff using the same format and attach the diagram's SVG. Put the comprehension check at the end of the PR body.

PR の説明に使うとき

When Explaining a PR

問いは「この PR がマージされたら、何が変わるか」「何が壊れうるか」にする。差分はファイル順ではなく、説明の順に並べる（literate diff）。

実物は次の 2 つ。

```
vlmkit-anim pr --base origin/main
```
の変更地図
変更前後で振る舞いが変わる最小の例（テストの追加・変更から選ぶ）

Ask “What will change if this PR is merged?” and “What could break?” Order the explanation by the flow of the explanation, not by file order; this is a literate diff. There are two real artifacts.

The change map produced by
```
vlmkit-anim pr --base origin/main
```
The smallest example whose behavior changes before and after the change, selected from the added or modified tests

やってはいけないこと

Things Not to Do

出力を打ち直す。 貼る。検証スクリプトが照合する。
図を記憶から描く。 事実シートを先に作る。図が事実シートと食い違ったら、図が間違っている。
読み手の既知を説明する。 ペルソナの「知っている」にあるものは削る。
緑を過大に報告する。 「検査が通った」と書くときは、何の検査が、どの範囲で通ったかを書く。

Do not retype outputs. Paste them. The validation script will compare them.
Do not draw diagrams from memory. Create the fact sheet first. If the diagram conflicts with the fact sheet, the diagram is wrong.
Do not explain what the reader already knows. Remove anything listed under the persona's “Knows” section.
Do not overstate a green result. When saying “the check passed,” state which check passed and the scope in which it passed.

ファイル

Files

パス	内容
`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 シーンと事実シート

Path	Contents
`references/persona.md`	Persona template and instructions for creating one
`references/writing.md`	Material structure, style, and instructions for creating comprehension checks
`references/figures.md`	Mapping from questions to diagram types, fact-sheet creation, and the vlmkit-anim workflow
`scripts/verify-doc.mjs`	Verification of checks, diagrams, quotations, and HTML
`scripts/build-html.mjs`	README.md → self-contained HTML with SVGs inlined
`scripts/figure-check.mjs`	Renders and checks manually written SVG / HTML / D2 / Mermaid diagrams for overlaps, overflow, border or line intersections with text, text that is too small, and fact-sheet consistency; also produces sheets for visual review
`scripts/figure-arrows.mjs`	Checks arrow readability, including two arrows running alongside or overlapping each other, arrows piercing a box, crossings, detours, and reversed direction; also creates sheets with one edge highlighted at a time. Used by figure-check
`scripts/figure-variants.mjs`	Renders and scores layout candidates for D2 / Mermaid using TALA seeds, ELK, dagre, and orientation
`scripts/icons.mjs`	Finds icons in the Iconify sets lucide and logos, arranges candidates on one sheet, places an icon beside a diagram, and records its source in ICONS.md
`scripts/tlc-to-scene.mjs`	Converts a TLC state graph and counterexample into a vlmkit-anim state-machine scene and fact sheet