zekainie/universal-examprep-skill/exam-study-guide

Exam Study Guide

Purpose

After teaching the current chapter, build its validated typed Study Guide manifest; in visual mode, compile that manifest into a readable, self-contained HTML Study Guide and printable PDF before phase completion. A Study Guide is a teaching artifact, not a dump of the wiki and bank: it groups knowledge points with every mapped lecture, homework, Quiz, mock-exam, past-exam, or textbook example and explains each one through formula selection, variable mapping, substitution, solution, a beginner-first explanation of why the answer follows, and source trace. Keep Markdown/JSON as auditable sources and never overwrite them with a derived artifact.

Activation

Require explicit study_state.json.processing_mode=full. Lightweight mode never invokes this module, even for a one-shot handout request; explain that Study Guide generation requires switching to full processing and reconfirming the start gate.

Use this module after the exam workspace/current chapter are confirmed and its substantive teaching is persisted, but before complete-phase in a structured workspace. Restore the current phase and effective artifact_mode from study_state.json before selecting <N>. chat still builds and imports the mandatory typed profile=full manifest, then stops without HTML/PDF; a recognized standing visual preference continues through rendering, receipt binding, and all-page QA. A direct one-shot handout request follows its explicit output scope without rewriting the stored preference. Never inspect or infer the student's subscription. Preserve the parent exam-coach language and provenance contracts in all chat summaries.

Inputs

• Exactly one current-chapter references/wiki/chNN*.md file, used as source evidence rather than pasted wholesale.
• Optional study_state.json; its canonical language-neutral language code (zh / en / bilingual; legacy/display aliases 中文 / English / 双语 migrate on read) controls all agent-generated headings, notices, explanations, labels, and summaries. Missing state follows the session default (English unless the student opened in Chinese); the script's Chinese empty-value fallback exists only for legacy workspaces and is not a new-session language decision.
• The current-chapter slice of references/teaching_examples.json, every current-chapter entry in references/quiz_bank.json, and every typed current-chapter question unit, de-duplicated by item ID. A legacy gradable=false record remains a teaching example in the guide but is never served or graded as a quiz.
• A substantive notebook/chNN.md plus the validated typed teaching manifest notebook/chNN.guide.json.
• Workspace-local images under references/assets/ referenced by the typed manifest.
• For ingestion-v2 workspaces, current validated .ingest/canonical_groups.jsonl and .ingest/source_conflicts.jsonl facts. These are revision-bound derived facts, not replacements for source occurrences or item/unit IDs. Do not preload unrelated chapters or hand-fold near matches.
• For ingestion-v2, .ingest/claim_records.jsonl and the matching .ingest/claim_verification_receipts/chNN.json are mandatory typed-guide inputs. The validator recomputes them against the current manifest and live source/content/group/conflict facts. The receipt's fact_snapshot_sha256 also binds current build/parser/page-quality/review facts into its ID, so a parser identity revision requires re-verification even when content units are unchanged. Legacy/v1 compatibility is read-only for an existing canonical manifest and must not be described as having this v2 evidence. The receipt scope is location_only, never semantic proof.

Use only $...$ and $$...$$ as formula delimiters in source Markdown. Forms such as (A\cup B), [P=\frac{...}], \(...\), and \[...\] are not valid framework input. Confirm and migrate the source explicitly; never guess-rewrite a formula.

Workflow

1. Restore study_state.json, resolve output intent, and run validate_workspace.py <ws> --json. Read the explicit .ingest/build_manifest.json.pipeline_version; never infer or delete it. Only ingestion-v2 follows the author/compiler/claim path in steps 2-6. An explicit ingestion-v1 workspace may only read its existing canonical manifest through the legacy compatibility path below; it cannot import, relocalize, or render a new Study Guide and must never claim the v2 claim/receipt gate. A failed v2 command does not authorize downgrading to v1. chat stops after the canonical profile=full manifest import; visual continues through rendering and all-page QA. Persist a standing choice only through update_progress.py set --artifact-mode chat|visual. Separately resolve answer_explanation_mode=ordinary|isolated. Missing, legacy, or invalid state has stored-schema fallback ordinary, which still requires a detailed beginner-first explanation for every item without an isolation claim. Before authoring a full-v2 Guide, perform a native-child capability handshake: require one fresh independent child context per item plus enforceable restriction of that child's task input and tools to the exact request. When verified, default to isolated unless the user opted out, persist it, and disclose once that it consumes extra host quota/time; no separate API key or external-upload consent is needed. Any missing, inherited, or unverified boundary keeps ordinary and must be named. A separately billed external Provider is available only when the user explicitly requests it; before persisting that fallback, retain the two-stage no-upload exact plan and exact-plan pricing/privacy/upload consent. Never infer either capability or upload permission from a model family, subscription, API key, full, or visual.
2. For ingestion-v2, prepare the revision-bound current-chapter packet and annotation template; do not hand-copy source facts or reverse-engineer the compiler source:

``text python scripts/study_guide_author.py --workspace <ws> prepare --chapter <N> --json ``

This fixed command atomically writes notebook/chNN.authoring-packet.json and the deliberately incomplete notebook/chNN.authoring-annotations.template.json; its JSON result reports both paths plus the template hash. Exit 10/status=blocked forbids authoring until every reported review, conflict, source, asset, and denominator blocker is resolved. The packet binds source/fact/asset revisions and contains the exact semantic units, formulas, items, prompt/answer assets, and source locations the agent may use.

1. Read the generated template instead of guessing the annotation schema. Copy only its annotations object to notebook/chNN.authoring-annotations.json, then replace every empty value and __...__ sentinel. The template already contains the exact ID and field shape for every formula group and walkthrough item, plus an explicit knowledge-point schema placeholder and the full inventories to partition. The wrapper says template_status=incomplete and valid_annotations=false; the template itself and its untouched inner object are intentionally invalid and cannot satisfy persistence, compilation, or completion. Author only explanations in the target file, bound to the packet's packet_sha256. Do not change packet IDs, source text, exact LaTeX, assets, locations, or source roles. Use the canonical zh|en|bilingual language shape and explicit provenance for every authored field. A translation must be ai_translation and remain visibly AI-labelled; unsupported reasoning uses visibly labelled ai_supplement, never fake material provenance. In ordinary, the template also requires each item's detailed zero-prerequisite answer_explanation and exact per-language ai_supplement provenance; it must explain symbols, formula/rule choice, substitutions or reasoning, every subpart, and final meaning without merely repeating the answer. In isolated, do not author that field in annotations; step 4 supplies it through the receipt-bound extension. Each item must map to at least one knowledge point. A knowledge point may have example_ids=[] when the materials truly provide no matching item; the compiler emits the active-language “materials do not provide a corresponding example” notice. Knowledge points still exactly partition semantic units/formula groups, and all items remain globally covered. If a crop-receipt-only upgrade changes the packet after a large canonical annotations file was already authored, run study_guide_author.py rebase-annotations --chapter <N> instead of hand-editing or regenerating it. That command may change only packet_sha256, add a missing mode binding on the compatible path, and remove paired legacy self_check fields; it atomically publishes only after the entire current annotation validator passes against the new packet. Any item/formula/knowledge-point drift is refused.
2. Only when answer_explanation_mode=isolated, generate exactly one isolated answer explanation per item before persistence. In ordinary, skip this entire step: study_guide_explain.py status reports disabled/not_applicable, and every mutating explainer command must fail. The protocol script never calls a provider itself: it emits one hash-bound request at a time. The preferred host-native route must create a fresh independent, tool-disabled child context containing only that request's fixed instruction, exact question, exact answer when present, target language, and listed item-scoped assets; it uses the current host allowance and no separate API key. Do not batch multiple items into one context, add the parent conversation, course history/wiki/retrieval, expose a whole page containing unrelated questions or answers, or let the child browse the workspace/network. If the host cannot enforce these boundaries, use ordinary. A bundled external-Provider adapter is only an explicit-user-request fallback: it may prepare a non-uploading exact plan after the first consent, and its run requires the second exact-plan consent. Adapter completion finalizes only the isolated explanation receipt, not notebooks, compiled Guide, claims, import, rendering, QA, or phase completion.

``text python scripts/study_guide_explain.py --workspace <ws> prepare --chapter <N> --json python scripts/study_guide_explain.py --workspace <ws> status --chapter <N> --json python scripts/study_guide_explain.py --workspace <ws> show --chapter <N> --request-id <request_id> --json # Call one fresh/stateless tool-disabled model with exactly that request. The model result contains only answer_explanation plus non-rendered coverage. python scripts/study_guide_explain.py --workspace <ws> make-host-receipt --chapter <N> --request-id <request_id> --invocation-id <unique_id> --isolation-mode <fresh_context|stateless_api> --provider <provider> --model <model> --json python scripts/study_guide_explain.py --workspace <ws> import-result --chapter <N> --request-id <request_id> --input <one-model-result.json> --host-receipt <one-host-receipt.json> --json python scripts/study_guide_explain.py --workspace <ws> finalize --chapter <N> --json ``