explainer-book

explainer-book

explainer book version. When a single quick-study resource (within 20 minutes, one example each) is not enough, split it into chapters and turn it into alearn by doingresource.

For the persona, diagrams, and verification mechanisms, use explainer as is. First read ../explainer/SKILL.md . What this skill adds is the design and inspection of the book as a whole.

The script is in this skill's directory (hereafter <skill>）の scripts/ is located in. verify-book.mjs calls the neighboring explainer skill's scripts/verify-doc.mjs . Put the two skills in the same place. How to install dependencies is the same as "Preparation" in explainer .

When to make it a book

Make it a book if any of the following applies. If none applies, write it as a singleexplainer .

The reading time exceeds 20 minutes
The reader needs hands-on exercises (reading alone does not make them able to "judge")
The concepts have an order (you cannot read B without knowing A)

Structure

<topic>-book/
  README.md            目次：想定読者、章ごとの「読み終えたらできること」、章の依存図、再現方法
  book.json            章の順序・学習目標・導入する概念・演習（references/book-json.md）
  01-quickstart.md     最初の章は必ず quickstart：理論の前に、動く結果に着く
  02-….md              concept：1 章 1 つの判定を身につける
  03-….md              practice：演習が中心
  checks.json          本文の出力と演習の答えを再生成するコマンド（explainer と同じ形式）
  examples/            章で使うコード・モデル。演習の出発点と答えを別ファイルにする
  figures/             book-map.*（生成）と各章の図

Procedure

1. ペルソナ     explainer と同じ。「怪しいところ」から、本全体の問いを 1 つ決める
2. 目標を並べる  問いに答えるために読み手ができるべき判定を 3〜6 個。1 章に 1〜2 個
3. 概念の順序   各判定に要る概念を書き出し、どの章で導入するかを決める（book.json introduces / requires）
4. 実物を先に   各章の例と演習を作り、走らせる。演習は「出発点で落ちる」「答えで通る」を両方確かめる
5. 章を書く     explainer の writing.md の型。章の冒頭に所要時間とゴール、末尾に理解度チェック
6. 検証         node <skill>/scripts/verify-book.mjs <book-dir> [--write]
7. 読ませる     first-reader で、少なくとも 01-quickstart と演習の章を、ペルソナ本人に読ませる（explainer の手順 8）
8. 渡す         dist/index.html と、各章の 1 行要約。未検証の点を明記

2. Learning objectives

Write objectives as "what will the reader be able to judge after finishing". Do not write "understand ~" because it cannot be checked.

Bad example: "Understand CTI"
Good example: "When a CTI appears, be able to judge with TLC whether the conditions are merely too weak or the property is truly violated"

Attach at least one comprehension-check question to each objective (）。

3. Order of concepts

Concepts the persona already knows are written in assumed . Do not explain them.
For all other concepts, exactly one chapter introduces them. If they appear in the body of an earlier chapter, verification fails.
Concepts that a chapter presupposes are written in requires . They become arrows in the dependency diagram.

4. Exercises

Run and verify the answers to exercises as well. An exercise with a wrong answer teaches the wrong thing.

kind	Example	Check
`write`	Have them write conditions, functions, and settings	`starter`: a check that verifies that running it as-is from the starting pointfails.`answer`: a check that verifies that itpasseswith the answer
`check`	Have them run a tool and judge	`answer`: a check that regenerates the output that serves as the basis for the judgment

Put answers in the <details> of the same section as the exercise.
Place  before the exercise.

5. Writing chapters

explainer In addition to the writing style of , follow the following.

In the quote block at the beginning, write the required time, the goal (the objective of that chapter), and the prerequisites (previous chapter).
At the end, link to the next chapter (→ [02 …](02-….md)). In HTML, navigation to the previous and next chapters and the table of contents is added.
When using the results of a previous chapter, refer to it by chapter number ("the 3 checks in Chapter 1"). Do not repeat the same explanation.
Replace results you reasoned out by hand ("this state cannot be reached," "it happens in this order") with the tool's output. Reasoning goes wrong.

6. Verification

node <skill>/scripts/verify-book.mjs <book-dir>           # 検査
node <skill>/scripts/verify-book.mjs <book-dir> --write   # 依存図と SVG を作り直す

Whole-book checks:

Check	Failing condition
chapters	A chapter file is missing.`NN-` The numbers of do not match the order in book.json. Chapter 1 is not quickstart
objectives	There is an objective that has no quiz attached. A quiz names an objective from another chapter
concepts	A concept is used in a chapter before it is introduced.`requires` has not been introduced.`introduces` It is declared as but does not appear in the body text
budget	The estimated reading time of the body text (500 characters/minute + 15 lines of code/minute) is `minutes` exceeds
exercises	There is no mark. The answer is not in `<details>` . A check is not in checks.json.`write` There is no starter that fails the exercise
map	`figures/book-map.*` does not match book.json. There is no diagram in the README

After that, pass the README and all chapters to verify-doc.mjs --pages . Inspect the output's quotes, diagrams, inter-page links, and each page's vlmkit gate.

book verdict: VERIFIED Fix it until it becomes .

Things you must not do

Add chapters and dilute the content. If a chapter has no objective, or the comprehension check does not ask about the objective, that chapter is unnecessary.
Do not run the exercise answers.
Repeat the previous chapter's explanation. Refer to it by chapter number.
Rewrite the wording just to pass verification. If it fails the concept check, move the definition to an earlier chapter or reconsider the chapter order. Do not escape by replacing it with a synonym.

File

Path	Content
`references/book-json.md`	All fields of book.json
`scripts/verify-book.mjs`	Whole-book checks → verify-doc.mjs
`../explainer/scripts/build-html.mjs`	Multiple pages to HTML (with table of contents and previous/next chapter navigation)