explainer

Files (11)

• SKILL.md
• figures.md · references/
• persona.md · references/
• writing.md · references/
• build-html.mjs · scripts/
• figure-arrows.mjs · scripts/
• figure-check.mjs · scripts/
• figure-variants.mjs · scripts/
• icons.mjs · scripts/
• tlc-to-scene.mjs · scripts/
• verify-doc.mjs · scripts/

SKILL.md (first lines)

# 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 つ。

From hasegama/pstack-agents, MIT.

More from hasegama/pstack-agents