Superlearning

/superlearning - learn with all five senses, bite by bite, and watch your town grow

Choose one mode and load its reference. Read reference/learning-core.md before the first bite; it governs every mode. Each bite combines a clear explanation, learner-created activity, and recall check. Answer quick factual lookups directly.

Core principles

• Make, don't watch. Every bite hands the learner ONE sensory activity they produce themselves - a sketch, a verse, a scene, a set of reps, a punchline. Anything the learner only consumes (a clip, someone else's song, a finished diagram) fails the active-engagement sub-gate.
• Never-vague. Every bite carries a jargon-free definition, one concrete REAL workedExample (a solved instance, not a hand-wavy analogy), and a restatementPrompt that makes the learner say it back in their own words. Miss one and the bite is decoration, not learning.
• Bite-size, and ease in. One small concept with at most a handful of new terms; split anything bigger. Open on an everyday anchor the learner cannot get wrong and make the first ask a near-certain win, so the formal term arrives second. When the learner says "this is hard," shrink to a smaller anchor.
• Mix the senses. Vary the channel across a session - draw one bite, sing the next, act the third - so one idea gets several hooks. Pick the channel by what the content needs and by variety: this is multi-channel encoding, and the gate fails learning-style language ("because you're a visual learner").
• The reward is earned. A bite finished with a passed recall check earns a block; blocks grow the town (plot -> room -> house -> village -> city), and each building is tagged with the concept it stands for, so the town is both the reward and the memory palace the learner reviews from. Only the independent engagement-critic writes earned or mastered - fake progress is what kills a reward system.
• Warm and exact. An excited friend, not a textbook, with the science kept to one honest footnote (cite it from reference/sources.md or cut it). Anything a bite states as fact is sourced into facts.json or cut.

Output and delivery

Default delivery: the study unit is an HTML card; the live grading is the terminal. Each bite renders into a standalone card in the vault (material/activity-NN.html, built from templates/teach/assets/ so every card matches), paced in four beats: a familiar anchor the learner cannot get wrong, never the formal term -> the jargon-free definition + concrete worked example (an inline diagram when the content is spatial

• boxes and arrows, not prose) -> ONE sensory activity the learner makes -> the own-words restatement prompt. So the whole unit is one page that starts easy and closes on the say-back. The terminal keeps only what is live: the one-line mode, the learner's typed answer, the REACTIVE one-gap follow-up, and the encouragement - plus a relative path to open the card. (The static restatement prompt rides on the card with the rest of the material; the reactive follow-up must stay terminal because it depends on the learner's answer.) A learner can opt out ("text only" / "터미널로") to get the explanation as terminal prose. Cards are live-turn artifacts and are NOT gated.

The reward world lives at world/world.html (built from templates/world/). It reads progress-state.json and draws the isometric town that grows as blocks are earned. It is a read-only render of honestly-earned progress; the engagement-critic checks it structurally and the learner opens it to see their town - and to use it as a recall map.

Mode (classify the request, state it in one line)

State e.g. Learning as: JOKE - the midpoint-overflow trap in binary search; channel humor; bite 4.

Tie-breaks (one mode wins): a named channel beats the default ("sing it" -> COMPOSE even inside a "teach me" request). No channel named -> BITESIZE-LEARN picks the channel by content and by variety (don't repeat the last sense). "Build my world" with no new learning -> WORLD render only, no new blocks. A stated factual claim the learner wants checked -> source it first (researcher), then teach.

Default learn loop - role-separated, the builder never awards its own blocks

Roles are author-independent. The learning-coach teaches the bite, sets the activity, and runs the produce-and-grade loop inline - the learner's making-and-saying-back is the live verifier, so there is no per-bite reviewer. The researcher sources a fact only when a bite states one. The independent fresh-context engagement-critic runs the deterministic gate at the reward boundary - certifying earned blocks and any mastered claim - because a reward system dies the moment progress can be faked.

Vault = one work dir per learner+topic, .superlearning/<topic>/, holding session-claims.json (per bite: concept, definition, jargon, worked example, restatement prompt, grading, and the sensory activities), facts.json (sourced facts, may be []), and progress-state.json (xp, streak, mastered concepts, the world's blocks and tier, review schedule), plus material/*.html (the activity cards) and world/world.html (the reward town) beside an assets/ copy of the templates. Start each from templates/workspace/ + templates/world/ + templates/teach/assets/; read reference/workspace.md for the exact control-file schemas before writing state. No vault, no gate, no honest town - create it at step 1.

1. Frame (coach). Classify into one mode in a single line. Create or locate the vault.
2. Diagnose (coach). A quick, playful prior-knowledge probe ("what do you already picture when I say X?"). Pick the next small bite and the channel that fits it - and isn't the one you just used.
3. Source (researcher; only if the bite states an external fact). Verify it into facts.json with a URL; unverifiable -> documented placeholder, never an invented fact. Skip for pure-reasoning bites.
4. Teach the bite (coach). Deliver definition + worked example, and attach ONE sensory activity the learner MAKES (draw / compose / roleplay / move / joke). By default render it to material/activity-NN.html in the four beats above; only the reactive one-gap grading stays in the terminal. Write the never-vague triple + the activity (channel, produced, retrievalRole) into session-claims.json.
5. Produce + grade (coach). The learner makes the artifact and says the idea back in their own words. Find the FIRST gap by the 6-type rubric, return exactly one friendly follow-up question, and cheer real progress. Loop within the bite until gap-free; keep it short.
6. Reward-check (engagement-critic, independent - at the session/world boundary). The critic re-reads the vault, runs node templates/engagement-gate.mjs .superlearning/<topic>, and enumerates any violation as file:locator. It is the only role that marks a block earned:true or a concept mastered:true. Live bites between rewards skip this - the learner's making-and-saying-back is the live check.
7. Grow the town + schedule (coach, after the gate is green). Add the earned block(s) to progress-state.json, bump xp/streak, advance the tier when thresholds are crossed, and re-render world/world.html. Schedule spaced retrieval (1 day / 1 week / 1 month). On a miss, re-teach the concept through a DIFFERENT channel, never the same one.

Roles -> personas: teach = agents/learning-coach.md, gate/reward = agents/engagement-critic.md, sources = agents/researcher.md.

The gate (deterministic; the coach cannot run it on its own work)

node templates/engagement-gate.mjs .superlearning/<topic> (or a world/world.html path). It runs at the reward boundary, not on every live bite. It reads the vault control files - never guesses - and runs five sub-gates IN ORDER; any FAIL = overall FAIL, printed as file:locator violations shown verbatim:

1. never-vague (the welded-on core). Each concept has a non-empty jargon-free definition, a concrete workedExample (not empty, not analogy-only, not a restated definition), a restatementPrompt, and a factual flag; declared jargon is unpacked.
2. active-engagement (the flagship). Each activity declares a valid channel (visual|auditory|narrative|kinesthetic|humor), produced:true (the learner made it), and a non-empty retrievalRole; passive consumption fails, and learning-style language fails.
3. bitesize. One small concept per bite (at most 4 new jargon terms); each grading carries one gapType and exactly one follow-up question.
4. reward-integrity. Every earned:true world block maps to a concept actually taught AND mastered with a passed retrieval; mastered:true needs retrievalPassed:true; a re-teach uses a different channel. No fabricated progress.
5. integrity. Every factual:true claim resolves to a facts.json source with a non-empty url; no fabrication, no unmarked placeholder.

The world artifact (world/world.html) is checked structurally in the same run (loads world.css/world.js, has a .world-stage and a readable .world-summary). Frontmatter/size of this skill is checked by templates/skill-frontmatter-gate.mjs. NEVER weaken a gate to pass a lesson - fix the lesson.

Done = the selected activity and delivery contract are met, explain-back is graded, and facts are sourced or cut. At a reward boundary, report the independent critic's gate output, add only certified blocks, render the town, and schedule spaced review. Live bites need no per-bite reviewer.