1. Declaring the aim
Having read a document is not the same as having correctly understood its claims, premises, and exceptions. This skill checks understanding with multiple-choice questions based on the material, accumulates explanations in 2 explainers, and feeds back to the writer the paragraphs where misreadings concentrate.
The explainers are 2 volumes with different roles. The picture-based note (HTML) uses large pictures and single words to convey intuition, and the textbook (PDF) nails down the details with definitions, formulas, and worked examples. The learning state is kept in .rikai/ next to the material, and next time it reviews not-yet-mastered points from a different angle.
<SKILL_DIR> is replaced with the real path of the directory containing this SKILL.md .
2. Output policy
- All questions are created at once and presented in a one-page form. The default is 10 questions, and if the user specifies a number, follow it.
- After grading, the only thing output to the terminal is a table summarizing, for each question, correctness, the correct answer, and 1 line of evidence from the source text. Do not ask for the reason for wrong answers.
- Explanations are written in the explainer. Do not write them to the terminal or to study.md.
- Write what is shown to the user in the user's language. The user's language is the language used in the request, and if the user specifies a language, it is that language. If the language cannot be determined from the request (for example, when only a file path is given), use Japanese. This applies to questions, choices, explanations, the terminal result table, and everything else communicated to the user. Quotations from the source text remain in the material's language. Script output is in Japanese, so when communicating it to the user, rephrase it into the user's language (URLs and paths stay as they are). If an explainer already exists, continue writing in that explainer's language (change the language only when the user requests it). The body of study.md (introduction and feedback report) is also written in the user's language, but the frontmatter state values and keys are fixed regardless of language (references/study-format.md §3・§4)。
- The format standards are as follows; read the applicable one before writing it.
| Target | Standard |
|---|---|
| Extracting points and creating questions | references/question-design.md |
| State and feedback report | references/study-format.md |
| Question data, answers, answer codes | references/quiz-format.md |
| Picture-based note | references/explainer-html.md |
| Textbook | references/explainer-textbook.md |
3. In scope / Out of scope
- In scope: Documents and materials from which claims, premises, and exceptions can be extracted. Japanese materials are the main target.
- Materials in other languages: Treat without refusing. Extract the issues from the source text, and write the questions and explanations in the user's language (not necessarily Japanese. §2).
- Out of scope: Materials whose body text cannot be read, and materials for which the correct answer's basis cannot be determined because there is no source body text. Request a readable format or the provision of the body text, and do not create questions by guessing.
- Processing scope: Treat the materials as read-only. The only place to write is inside the
.rikai/folder at the same level as the target material.
4. Workflow (perform in this order)
Step 1. Determine the material and the files in .rikai/ confirm the file
Place the files in the .rikai/ folder at the same level as the target material. Create the folder if it does not exist. For the name, if the material name ends with .md , replace that extension; otherwise, append it to the original name.
| Material | State | Illustrated notes | Textbook |
|---|---|---|---|
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 |
Check in the following order.
- If there is a study.md in the old placement (placed directly next to the material), move it to
.rikai/. - If study.md exists, read the frontmatter and restore the issues, state, and challenge history. If it is in an old format, convert it to the current format using the migration procedure in references/study-format.md .
- If the question data for this material (
<資料名>.quiz.json) remains, the previous session was cut off midway. Follow the resume rules inreferences/quiz-format.md and resume from where it left off without creating new questions..rikai/is shared by all materials in the same folder, so do not look at the question data of other materials. - If this material's
<資料名>.study.pdfexists, it is a product of the previous method. Do not mention it here. Whether it is no longer updated and whether it may be deleted will be communicated together in Step 7 (the same applies even if study.md is already in the current format).
Step 2. Extract issues from the source text and verify the anchors
references/question-design.md , and extract issues from the source text's claims, premises, and exceptions. The primary key of each issue is "heading path + quoted string at the beginning of the source text"; record line numbers only as reference values.
Verify existing issues against the source text at session start. If a paragraph cannot be uniquely identified by prefix matching of the heading path and quoted string, change the state to 要再抽出 and do not ask questions on that issue. Do not maintain anchors based on line numbers alone.
Step 3. Select the issues to ask about and write the question data
The only targets for questioning are "issues that have experienced a wrong answer and are 復習中 " and "issues not yet attempted". Exclude issues whose state is 卒業 or 要再抽出 . Ask about the same issue only once per session. If the targets for questioning do not reach the specified number of questions, ask only as many as there are.
When there are more topics eligible for questions than the specified number of questions, select topics where the user has experienced incorrect answers first. Among those, give top priority to topics where the previous attempt was answered incorrectly. This is the order of "which topics to select," not the order in which questions are presented. The order of presentation is scripts/build_quiz.py randomizes, so the question data may be written in any order. Make sure the user cannot tell which questions are review questions before solving them. Do not write "review" or similar in question texts or form headings. The fact that a question was a review question is first communicated in the results table after grading (Step 5).
If there are no topics eligible for questions at all, do not present questions, tell the user so, skip Step 4 and Step 5, and perform Step 6 and Step 7. If any topics had their state changed in Step 2, save study.md before proceeding to Step 6.
The session identifier is session-YYYYMMDD-HHMMSS(the current time). This is to prevent two sessions on the same day from having the same identifier. For review questions, read the entire attempt history for that topic and create them according toreferences/question-design.md 's different-angle determination rules.
python3 , you may write both questions and choices in any order (the same applies when presenting questions as text).scripts/build_quiz.py reorders the questions and choices, reassigns question numbers and ids, and writes them back to the question data, so do not decide the position of the correct answer yourself.python3 is not available and questions are presented as text only, obtain the current time immediately before presenting the questions and determine the position of the correct answer withreferences/question-design.md §5 の (epoch 秒 + i) mod n . In this case, decide the order of the questions yourself as well. Do not group review questions at the beginning; mix them with questions on new topics.
Write all questions into the question data in the format references/quiz-format.md Write it in the question data in the format. For each question, the topic title (title) and the anchor (anchor). This is because topics extracted for the first time are not in study.md until they are saved after grading, so topics can be restored from the question data if the process is interrupted.
In the question data's lang , write the language tag of the user's language (such asja、en ). For fixed form text, built-in text is used for Japanese and English. For other languages, write all form text in ui (references/quiz-format.md §2.1)。
Step 4. Assemble the form and receive answers
Use python3(on Windows, python や py -3 ) to assemble the form and receive answers.python3 In an environment withoutpython3 is available, assemble the form first even when presenting with priority 4. This is because the script reorders the choices and writes them back to the question data (the assembled form is not used). When presenting as text, re-read the question data immediately before presenting, and present in the order and with the ids as written. Presenting from question texts left on hand before the write-back will cause the ids to differ from the question data and result in incorrect grading.
First, assemble the form. If there is an error in the question data, the script will stop and indicate the location, so fix it and run it again. The script reorders the questions and choices and writes them back to the question data, so use the question data after it has been written back for grading. If you are resuming an interrupted session and the question form already exists,--no-shuffle to keep the order unchanged (references/quiz-format.md §5)。
python3 "<SKILL_DIR>/scripts/build_quiz.py" --data "<出題データ>" --out "<出題フォーム>"
Next, receive the answers. Do not guess the host name or execution mode; look only at the means available at that point and choose them in order from the top.
| Priority | Condition | Procedure |
|---|---|---|
| 1 | Commands can be run in the background, and you will be resumed when they finish | Below, serve in the background. Tell them in one sentence that the form has been opened, andserve also convey the URL of the [quiz_server] フォーム: http://127.0.0.1:… line output by as is (so they can open it manually if the browser does not open) and end the turn. When resumed by the command's completion, if the exit code is 0 proceed to Step 5; if 2, move to Priority 3 |
| 2 | There is no background execution, but you can wait for the command to finish | Below, serve に --timeout , specify a number of seconds shorter than the host's limit for waiting on commands, and run it. If the exit code is 0 proceed to Step 5; if 2, move to Priority 3 |
| 3 | serve finished with exit code 2 (timeout), or the command's completion cannot be waited for |
If the form is already open, submitting in that tab will display the answer code. If it is not open, tell them the path of the question form and have them open it in a browser and submit. Have them paste the displayed answer code, and use the code below to make it into an answer file |
| 4 | Browsers cannot be used | Re-read the question data and, keeping the written order and ids, present all questions and choices as text and end the turn (as in the paragraph above,python3 if present, complete assembling the form first). Have them return answers in the format "1:b 2:a", and use the code below to make it into an answer file.python3 If there is no , do not create an answer file and use the returned answer code as is in 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 pass the pasted answer code enclosed in single quotes (replacing the 1:b 2:a part in the example above). Do not put the pasted string or the document title in double quotes. This is because the shell interprets $ and backticks. The reliable way is to specify - and pass it via standard input (--code -、--escape -)。
serve は 127.0.0.1 serve the form, open the browser, receive one submission, write the answer file, and exit. Exit code 0 means saved, 1 means an input error, and 2 means time expired. For 1, fix the displayed error and run again. If the error cannot be fixed (for example, the port cannot be opened), move on to priority 3. If the browser did not open, [quiz_server] ブラウザを開けませんでした。上の URL を手動で開いてください is displayed, so tell the user the form URL.
code exit code 1 indicates that the pasted code does not match the question data. Tell the user the displayed error and have them paste it again. Do not supplement or guess answers.
In non-interactive execution, this falls under priority 4, and the process ends with the question text awaiting an answer left in the final output.
Step 5. Grade and save study.md
Read the question data and the answer file, and for each question compare the answer with correct . If the answer file's session_id differs from the question data, do not grade and return to Step 4. If the answer file could not be created (python3 is not available), use the returned answer code as the answer and verify yourself that each question has exactly one valid choice.
For topics not yet in study.md (topics extracted for the first time), create the topic from the question data's topic_id・title・anchor , set the state to 復習中 , and then handle it. Append each question's attempt history in the format references/study-format.md . The date and time is the answer file's submitted_at(or the current time if there is no answer file), the question text, perspective, and choices are the values from the question data, andreasoning は null . Recalculate the state, regenerate the reflux report, and save study.md.
Once saved, immediately delete the question data, question form, and answer file. If they remain and the session ends, the same answer will be recorded again on the next startup.
Graduation is determined by whether the topic has been answered incorrectly. A topic with no incorrect answers becomes 卒業 on the first correct answer. A topic that has had an incorrect answer becomes 卒業 once the total number of correct answers reaches 3. Do not reset the correct-answer count even if an incorrect answer occurs in between.
After saving, display a results table in the terminal. The columns are question, type, topic title, correct/incorrect, correct answer, and one line of source evidence. For type, write "Review" if the topic has attempt history before this session, or "New" if it is the first time the topic has been asked. Write the table headers and contents in the user's language (only the quotation of source evidence stays in the material's language). If a topic title in study.md is written in a language different from the user's, display it translated in the table. Do not rewrite the values in study.md. For source evidence, quote one line from the paragraph that the topic's anchor points to. Do not ask for the reason for an incorrect answer.
Step 6. Update the explainer
Align the explainer with study.md. Include topics that have been attempted and whose anchors are valid (state is 復習中 か 卒業). Perform the following four actions and do not touch any other points. This applies to both explainers.
- Write new points that are not listed.
- For points whose status display differs from study.md, rewrite the display.
- For points that have wrong answers but no listed hesitation points, and for points whose hesitation points changed due to the current wrong answers, add the hesitation points.
- Status becomes
要再抽出Remove the section for the point that became this. This is because the supporting paragraph has been lost from the original text.
The language of the explainer is as stated in §2. When writing in a language other than Japanese, follow the "Language" section of each guide (picture-explanation notes: §9, textbook: §8), and also translate fixed wording.
Perform the update in the following order.
- Update the picture-explanation notes according to references/explainer-html.md . For the first time, start by copying assets/explainer-template.html .
- Update the textbook manuscript according to references/explainer-textbook.md . The format is determined by assets/rikai-textbook.sty , so do not add other packages to the preamble.
- Build the PDF.
python3 "<SKILL_DIR>/scripts/build_textbook.py" --input "<原稿>" --output "<PDF>"
Even with exit code 0, if a warning appears about characters not in the font,references/explainer-textbook.md fix it according to §5 and rerun. If it is a stray symbol, rewrite that character in the manuscript. If the warned character is a character of the language in which the textbook is written (such as Hangul), do not rewrite the character; specify a font that contains that character with \rikaifont (same §8). If the exit code is 1, fix the indicated line and rerun.\rikaifont After specifying fontspec if it fails with the error (font not found), that font is not installed. Do not modify the style file; choose another candidate from the same §8. If it fails three times in a row, leave the manuscript and report the failure (reruns with a different font candidate also count toward the three times). If no font containing characters of the textbook's language is installed, leave the manuscript, omit the PDF, and state in one line that a font for that language is needed (same as when xelatex is absent). If the exit code is 3, xelatex is absent. The PDF is an optional feature, so leave the manuscript and proceed. If the manuscript was created for the first time this time, convey the installation method shown by the script. Otherwise, state in one line that the PDF was omitted. Do not install LaTeX yourself.
python3 In an environment withoutbuild_textbook.py ,--escape cannot be run (andreferences/explainer-textbook.md §4.
Step 7. Report
Convey the following and finish.
- Paths of the picture-explanation notes and the textbook
- Titles of points that will be review targets next time
- If the PDF was omitted, the reason
- PDFs in the previous format (
<資料名>.study.pdfIf any remain, tell them it is no longer being updated and ask whether it may be deleted.
5. Guardrails (things you must not do)
- Do not explain using information not in the source text. Limit the basis for correct answers and explanations to the target material. Analogies and the numerical values, names, and scenarios in example problems are added by the explainer, and this must be stated explicitly within the explainer (in textbooks, add "(for explanation)" to the title of example problems; in languages other than Japanese, add the corresponding term).
- Do not ask for the reason for a wrong answer. Even if the user states a reason on their own, do not record it.
- Do not fabricate trick questions. Make correct answers, questions, and choices consistent with the claims in the source text, and do not use differences that cannot be judged from the source text or unnatural turns of phrase as grounds for right or wrong.
- Do not repeat the same question. When reviewing, check the challenge history and follow the different-angle judging rules.
.rikai/. Do not modify the material itself or other files.- Do not publish the generated output to external services. Keep the explainer and form as local files.
- Do not show issue IDs to the reader.
topic-NNNis an internal key for matching and must not appear in the terminal table or in the body of the explainer. - Do not install LaTeX on your own. Stop at explaining how to install it.
6. Final judgment criteria
Whether the user can distinguish the claims, premises, and exceptions in the source text and can reread the explainer for the issues they got wrong to correct their own misreading.