rikai — 読解度チェックスキル

1. 狙いの宣言

資料を読んだことと、主張・前提・例外を正しく理解したことは同じではない。本スキルは、資料に基づく選択式の問いで理解を確かめ、解説を 2 つの explainer に蓄積し、誤読が集中した段落を書き手へ還流する。

explainer は役割の違う 2 冊である。絵解きノート（HTML）は大きな絵とひとことで直感をつかませ、テキストブック（PDF）は定義・数式・例題で細部を詰める。学習状態は資料の隣の .rikai/ に残し、次回は未卒業の論点を別角度から復習する。

<SKILL_DIR> はこの SKILL.md があるディレクトリの実パスに読み替える。

2. 出力方針

• 問題は全問を 1 回で作り、1 ページのフォームで提示する。既定は 10 問で、ユーザーが数を指定したらそれに従う。
• 採点後にターミナルへ出すのは、問ごとの正誤・正答・原文の根拠 1 行をまとめた表だけである。誤答の理由は尋ねない。
• 解説は explainer に書く。ターミナルにも study.md にも書かない。
• ユーザーに見せるものは、ユーザーの言語で書く。ユーザーの言語とは依頼に使った言語であり、ユーザーが言語を指定したらその言語とする。依頼から言語を判断できない場合（ファイルのパスだけを渡された場合など）は、日本語を使う。問い、選択肢、解説、ターミナルの結果の表、そのほかユーザーに伝えることすべてが対象である。原文の引用は資料の言語のままにする。スクリプトの出力は日本語なので、ユーザーに伝えるときはユーザーの言語に言い換える（URL やパスはそのまま）。explainer がすでにあれば、その explainer の言語で書き続ける（言語を変えるのはユーザーが求めたときだけ）。study.md の本文（導入と還流レポート）もユーザーの言語で書くが、frontmatter の状態の値とキーは言語によらず固定である（references/study-format.md §3・§4）。
• 形式の基準は次のとおりで、該当するものを書く前に読む。

対象	基準
論点の抽出と問題の作り方	references/question-design.md
状態と還流レポート	references/study-format.md
出題データ・回答・回答コード	references/quiz-format.md
絵解きノート	references/explainer-html.md
テキストブック	references/explainer-textbook.md
ダッシュボード（フォルダ全体の進捗一覧）	references/dashboard.md

3. 対象 / 対象外

• 対象：主張・前提・例外を抽出できる文書や資料。日本語資料を主対象とする。
• 他言語資料：拒否せずに扱う。論点は原文から抽出し、問いと解説はユーザーの言語で書く（日本語とは限らない。§2）。
• 対象外：本文を読み取れない資料、出典本文がなく正答の根拠を確定できない資料。読める形式または本文の提供を依頼し、推測で出題しない。
• 処理範囲：資料は読み取り専用とする。書き込むのは、対象資料と同じ階層の .rikai/ フォルダの中だけである。

4. ワークフロー（この順序で行う）

Step 1. 資料と .rikai/ のファイルを確定する

ファイルは対象資料と同じ階層の .rikai/ フォルダに置く。フォルダがなければ作る。名前は、資料名が .md で終わるならその拡張子を置き換え、それ以外は元の名前に続けて付ける。

資料	状態	絵解きノート	テキストブック
docs/report.md	docs/.rikai/report.study.md	docs/.rikai/report.explainer.html	docs/.rikai/report.explainer.tex と .pdf
docs/report.pdf	docs/.rikai/report.pdf.study.md	docs/.rikai/report.pdf.explainer.html	docs/.rikai/report.pdf.explainer.tex と .pdf

.rikai/dashboard.html は、そのフォルダにある全資料の進捗一覧で、資料ごとには作らない（references/dashboard.md）。

次の順に確かめる。

1. 旧配置（資料の隣に直置き）の study.md があれば、.rikai/ へ移す。
2. study.md があれば frontmatter を読み、論点・状態・挑戦履歴を復元する。古い形式なら references/study-format.md の移行手順で現行の形式に直す。
3. この資料の出題データ（<資料名>.quiz.json）が残っていれば、前回のセッションが途中で切れている。references/quiz-format.md の再開規則に従い、新しい問題を作らずに続きから再開する。.rikai/ は同じフォルダの資料すべてで共有するので、ほかの資料の出題データは見ない。
4. この資料の <資料名>.study.pdf があれば、以前の方式の生成物である。ここでは伝えない。更新しなくなったことと、削除してよいかは、Step 7 でまとめて伝える（study.md がすでに現行の形式でも同じ）。

Step 2. 原文から論点を抽出し、アンカーを照合する

references/question-design.md を読み、原文の主張・前提・例外から論点を抽出する。各論点の主キーは「見出しパス + 原文冒頭の引用文字列」であり、行番号は参考値としてだけ記録する。

既存の論点はセッション開始時に原文と照合する。見出しパスと引用文字列の前方一致で段落を一意に特定できない場合は、状態を 要再抽出 に変え、その論点を出題しない。行番号だけを根拠にアンカーを維持してはならない。

Step 3. 出題する論点を選び、出題データを書く

出題対象は「誤答を経験して 復習中 の論点」と「未挑戦の論点」だけである。状態が 卒業 または 要再抽出 の論点は除く。同じ論点は 1 セッションに 1 回だけ出す。出題対象が指定の問題数に足りなければ、ある分だけ出す。

出題対象が指定の問題数より多いときは、誤答を経験した論点から先に選ぶ。その中でも、前回の挑戦が誤答だった論点を最優先にする。これは「どの論点を選ぶか」の順であり、出題する順ではない。出題の順番は scripts/build_quiz.py が無作為に並べ替えるので、出題データにはどの順で書いてもよい。どれが復習問題かは、解く前のユーザーに分からないようにする。問題文やフォームの見出しに「復習」などと書かない。復習問題だったことは、採点後の結果の表で初めて伝える（Step 5）。

出題対象が 1 つもなければ、出題せずにそう伝え、Step 4 と Step 5 を飛ばして Step 6 と Step 7 を行う。Step 2 で状態を変えた論点があれば、study.md を保存してから Step 6 に進む。

セッション識別子は session-YYYYMMDD-HHMMSS（現在時刻）とする。同じ日の 2 回のセッションが同じ識別子にならないようにするためである。復習問題は、その論点の全挑戦履歴を読み、references/question-design.md の別角度判定規則に従って作る。

python3 があれば、問題も選択肢もどの順で書いてよい（問題をテキストで提示する場合も同じ）。scripts/build_quiz.py が問題の順番と選択肢を並べ替え、問題番号と id を振り直して出題データに書き戻すので、正解の位置を自分で決めない。python3 がなく、問題をテキストだけで提示する場合に限り、出題の直前に現在時刻を取得し、references/question-design.md §5 の (epoch 秒 + i) mod n で正解の位置を決める。この場合は問題の順番も自分で決める。復習問題を先頭に固めず、新しい論点の問題と混ぜて並べる。

全問を references/quiz-format.md の形式で出題データに書く。各問には、論点の題名（title）とアンカー（anchor）も書く。初めて抽出した論点は採点後の保存まで study.md にないので、途中で切れたときに出題データから論点を復元するためである。

出題データの lang には、ユーザーの言語の言語タグ（ja、en など）を書く。フォームの固定の文言は、日本語と英語なら組み込みのものが使われる。それ以外の言語では、フォームの文言をすべて ui に書く（references/quiz-format.md §2.1）。

Step 4. フォームを組み立て、回答を受け取る

フォームの組み立てと回答の受け取りには python3（Windows では python や py -3 のことがある）を使う。python3 がない環境では、下の表の優先 4 だけを使う。フォームの組み立ても飛ばす。python3 があれば、優先 4 で提示する場合も先にフォームを組み立てる。スクリプトが選択肢を並べ替えて出題データに書き戻すためである（できたフォームは使わない）。テキストで提示するときは、その直前に出題データを読み直し、書かれている順と id のまま提示する。手元に残っている書き戻す前の問題文から提示すると、id が出題データと食い違い、誤って採点される。

まずフォームを組み立てる。出題データに誤りがあれば、スクリプトが箇所を示して止まるので、直して再実行する。スクリプトは問題の順番と選択肢を並べ替えて出題データに書き戻すので、採点には書き戻したあとの出題データを使う。中断したセッションを再開して出題フォームがすでにある場合は、--no-shuffle を付けて並びを変えない（references/quiz-format.md §5）。

python3 "<SKILL_DIR>/scripts/build_quiz.py" --data "<出題データ>" --out "<出題フォーム>"

次に回答を受け取る。ホスト名や実行モードを推測せず、その時点で使える手段だけを見て、上から順に選ぶ。

優先	条件	手順
1	コマンドをバックグラウンドで実行でき、終了時に自分が再開される	下の serve をバックグラウンドで実行する。フォームを開いたことを 1 文で伝え、serve が出力した [quiz_server] フォーム: http://127.0.0.1:… の行の URL もそのまま伝えて（ブラウザが開かなかったときに手で開けるように）ターンを終える。コマンドの終了で再開したら、終了コード 0 なら Step 5 へ進み、2 なら優先 3 に移る
2	バックグラウンド実行はないが、コマンドの終了を待てる	下の serve に --timeout を付け、ホストがコマンドを待てる上限より短い秒数を指定して実行する。終了コード 0 なら Step 5 へ進み、2 なら優先 3 に移る
3	serve が終了コード 2（時間切れ）で終わった、またはコマンドの終了を待てない	すでにフォームを開いているなら、そのタブで提出すれば回答コードが表示される。開いていなければ出題フォームのパスを伝え、ブラウザで開いて提出してもらう。表示された回答コードを貼ってもらい、下の code で回答ファイルにする
4	ブラウザを使えない	出題データを読み直し、書かれている順と id のまま、全問と選択肢をテキストで提示してターンを終える（上の段落のとおり、python3 があればフォームの組み立てを先に済ませておく）。回答は「1:b 2:a」の形式で返してもらい、下の code で回答ファイルにする。python3 がない場合は回答ファイルを作らず、返ってきた回答コードをそのまま Step 5 で使う

python3 "<SKILL_DIR>/scripts/quiz_server.py" serve --quiz "<出題フォーム>" --data "<出題データ>" --out "<回答ファイル>"
python3 "<SKILL_DIR>/scripts/quiz_server.py" code --data "<出題データ>" --out "<回答ファイル>" --code '1:b 2:a'

code の --code には貼られた回答コードを単一引用符で囲んで渡す（上の例の 1:b 2:a の部分を置き換える）。貼り付けられた文字列や資料の題名を二重引用符に入れない。シェルが $ やバッククォートを解釈するためである。確実なのは - を指定して標準入力から渡す方法である（--code -、--escape -）。

serve は 127.0.0.1 でフォームを配信してブラウザを開き、提出を 1 回受け取ると回答ファイルを書いて終了する。終了コードは 0 が保存済み、1 が入力の誤り、2 が時間切れである。1 のときは、表示された誤りを直して再実行する。直せない誤り（例えばポートを開けない）なら優先 3 に移る。ブラウザが開かなかったときは [quiz_server] ブラウザを開けませんでした。上の URL を手動で開いてください と出るので、フォームの URL をユーザーに伝える。

code の終了コード 1 は、貼られたコードが出題データと合わないことを示す。表示された誤りを伝えてもう一度貼ってもらう。回答を補ったり推測したりしてはならない。

非対話の実行では優先 4 に当たり、回答待ちの問題文を最終出力に残して終わる。

Step 5. 採点して study.md を保存する

出題データと回答ファイルを読み、問ごとに回答と correct を比べる。回答ファイルの session_id が出題データと違う場合は採点せず、Step 4 に戻る。回答ファイルを作れなかった場合（python3 がない環境）は、返ってきた回答コードを回答として使い、全問に有効な選択肢が 1 つずつあることを自分で確かめる。

study.md にまだない論点（初めて抽出した論点）は、出題データの topic_id・title・anchor から論点を作り、状態を 復習中 にしてから扱う。各問の挑戦履歴を references/study-format.md の形式で追記する。日時は回答ファイルの submitted_at（回答ファイルがなければ現在時刻）、問題文・観点・選択肢は出題データの値、reasoning は null とする。状態を再計算し、還流レポートを再生成して、study.md を保存する。

保存できたら、すぐに出題データ、出題フォーム、回答ファイルを削除する。残したままセッションが切れると、次回の起動時に同じ回答をもう一度記録してしまう。

卒業の判定は誤答経験の有無で分ける。誤答が 1 件もない論点は、最初の正解で 卒業 にする。誤答を経験した論点は、正解が通算 3 回に達した時点で 卒業 にする。誤答が挟まっても正解回数をリセットしない。

保存したら、ターミナルに結果の表を出す。列は、問、種別、論点の題名、正誤、正答、原文の根拠 1 行である。種別には、今回より前に挑戦履歴がある論点なら「復習」、初めて出題した論点なら「新規」と書く。表の見出しと中身はユーザーの言語で書く（原文の根拠の引用だけは資料の言語のまま）。study.md の論点の題名がユーザーの言語と違う言語で書かれていれば、表には訳して出す。study.md の値は書き換えない。原文の根拠は、その論点のアンカーが指す段落から 1 行を引用する。誤答の理由は尋ねない。

Step 6. explainer を更新する

explainer を study.md に合わせる。載せるのは、挑戦済みで、アンカーが有効な論点（状態が 復習中 か 卒業）である。次の 4 つを行い、それ以外の論点には触れない。2 つの explainer に共通の条件である。

1. 載っていない論点を新しく書く。
2. 状態の表示が study.md と違う論点は、表示を書き換える。
3. 誤答があるのに迷いどころがない論点、今回の誤答で迷いどころが変わった論点は、迷いどころを書き足す。
4. 状態が 要再抽出 になった論点の節は取り除く。根拠の段落が原文から失われているためである。

explainer の言語は §2 のとおりである。日本語以外の言語で書くときは、各ガイドの「言語」の節（絵解きノートは §9、テキストブックは §8）に従い、固定の文言も訳す。

更新は次の順に行う。

1. 絵解きノートを references/explainer-html.md に従って更新する。初回は assets/explainer-template.html を複製して始める。
2. テキストブックの原稿を references/explainer-textbook.md に従って更新する。体裁は assets/rikai-textbook.sty が決めるので、プリアンブルに他のパッケージを足さない。
3. PDF をビルドする。

python3 "<SKILL_DIR>/scripts/build_textbook.py" --input "<原稿>" --output "<PDF>"

終了コード 0 でも、フォントにない文字の警告が出たら、references/explainer-textbook.md §5 に従って直し、再実行する。紛れ込んだ記号なら、その文字を原稿で書き換える。警告の文字がテキストブックを書いている言語の文字（ハングルなど）なら、文字は書き換えず、その文字を持つ入っているフォントを \rikaifont で指定する（同 §8）。終了コード 1 のときは、示された行を直して再実行する。\rikaifont を指定したあとに fontspec のエラー（フォントが見つからない）で失敗したら、そのフォントは入っていない。style ファイルは直さず、同 §8 の別の候補を選ぶ。3 回続けて失敗したら、原稿を残して失敗を伝える（フォントの候補を替えた再実行も 3 回に数える）。テキストブックの言語の文字を持つフォントが入っていなければ、原稿を残して PDF を省き、その言語のフォントが要ることを 1 行で伝える（xelatex がないときと同じ）。終了コード 3 のときは xelatex がない。PDF は任意の機能なので、原稿を残して先へ進む。原稿を今回初めて作ったなら、スクリプトが表示した導入方法を伝える。そうでなければ、PDF を省いたことを 1 行で伝える。LaTeX を自分でインストールしてはならない。

python3 がない環境では、build_textbook.py を実行できない（--escape も使えない）。原稿は更新して残し、PDF を省いたことを 1 行で伝える（xelatex がないときと同じ）。資料名や論点の題名に含まれる特殊文字は、references/explainer-textbook.md §4 の表に従って手でエスケープする。

最後に、その資料がある .rikai/ のダッシュボードを再生成する（references/dashboard.md）。出題がなかったセッションでも行う。--lang にはユーザーの言語の言語タグを渡す。

python3 "<SKILL_DIR>/scripts/build_dashboard.py" --rikai-dir "<.rikai フォルダ>" --lang "<言語タグ>"

終了コード 2 は、同じフォルダに読めない study.md があることを示す。ダッシュボードは書かれているので先へ進み、Step 7 で資料名と理由を伝える。python3 がない環境では再生成できないので、省いたことを 1 行で伝える。

Step 7. 報告する

次を伝えて終える。

• 絵解きノートとテキストブックのパス
• ダッシュボードのパス（読めない study.md があれば、その資料名と理由）
• 次回の復習対象になる論点の題名
• PDF を省いた場合は、その理由
• 以前の方式の PDF（<資料名>.study.pdf）が残っていれば、もう更新していないことを伝え、削除してよいかを尋ねる

出題を伴わない依頼

次の依頼は、問題を作らずに応じる。どちらも Step 1 の確認（旧配置の移動と形式の移行）は行う。

• 進捗を見たい（「進捗を見せて」「ダッシュボードを開いて」など）: Step 6 の末尾と同じコマンドでダッシュボードを再生成し、パスを伝える。フォルダをまたいだ一覧を求められたときだけ --root を使う（references/dashboard.md §2）。
• 論点を手動で卒業にしたい（「この論点は復習済みにして」「〜は演習で解けたので卒業にして」など）: 論点を題名で特定し、対象をユーザーに確認する。確認できたら、その論点に manual_graduation（日時と、述べられた理由。理由がなければ null）を書く。状態を 卒業 にして study.md を保存する（references/study-format.md §3）。挑戦履歴には書かない。保存後に explainer（挑戦済みの論点だけ）とダッシュボードを更新する。
• 手動の卒業を取り消したい（「〜を復習に戻して」など）: その論点の manual_graduation を取り除く。挑戦履歴から状態を再計算して保存し、explainer とダッシュボードを更新する。

5. ガードレール（やってはいけないこと）

• 原文にない情報で解説しない。 正答と解説の根拠を対象資料に限る。たとえ話と、例題の数値・名前・場面は explainer が足したものであり、その旨を explainer の中に明記する（テキストブックでは例題の題に「（説明用）」、日本語以外の言語ではそれに当たる語を添える）。
• 誤答の理由を尋ねない。 ユーザーが自分から理由を述べても、記録しない。
• ひっかけを捏造しない。 正答、問い、選択肢を原文の主張と整合させ、原文では判断できない差や不自然な言葉尻を正誤の根拠にしない。
• 同じ問題を反復しない。 復習では挑戦履歴を確かめ、別角度判定規則に従う。
• .rikai/ の外に書かない。 資料本体と、他のファイルを変更しない。
• 生成物を外部サービスへ公開しない。 explainer とフォームは、手元のファイルとして置く。
• 論点 id を読者に見せない。 topic-NNN は照合用の内部キーであり、ターミナルの表・explainer の本文・ダッシュボードのどれにも出さない。
• 手動の卒業を挑戦履歴に書かない。 記録するのは manual_graduation だけである。ダッシュボードは読むだけで、study.md を書くのはこのスキルに限る。
• LaTeX を勝手にインストールしない。 導入方法を伝えるところまでにとどめる。

6. 最終判断基準

ユーザーが原文の主張・前提・例外を区別でき、誤答した論点を explainer で読み返して自分の誤読を修正できるか。