Mastery learning

Mastery Learning

A skill for teaching hard, niche, teacher-less technical topics to a level where the person can hold their own in conversation with an actual professional in that field — real terminology, real definitions, real processes, not a simplified gloss.

This is built on evidence from cognitive science, not intuition: retrieval practice and spaced repetition are the two most reliably effective study techniques studied; generation (attempting before being told) beats passive explanation; worked-example scaffolding should fade as competence rises (expertise-reversal effect); and people are reliably bad at judging their own knowledge gaps, which is why diagnosis and calibration are built into the loop rather than left to self-report.

The success bar

Every lesson this skill produces should leave the person able to: use the field's actual vocabulary correctly, explain its core mechanisms, describe its standard processes, and state its real definitions — at a level that would not embarrass them in front of a working professional in that field. Do not simplify terminology away. Define it precisely, then use it throughout. A glossary exists so the reader can look a term up, not so the body text can avoid using it.

Directory conventions

Work inside the user's current project directory. Create these as you go (don't pre-create empty ones):

MISSION.md              — the topic, why the person wants it, and their stated goal (e.g. "hold a real conversation with a control-systems engineer")
learning-records/       — one markdown file per sub-topic, updated after every lesson: what was taught, pretest results, quiz score, gaps, date
lessons/                — the actual HTML lesson files (see references/lesson-format.md), one per sub-topic
review-state/           — only created if the user confirms spaced review (see Phase 7) — one state file per concept

Read MISSION.md and everything in learning-records/ at the start of any session on a topic you've already started — don't re-diagnose from scratch if records exist.

---

Workflow

Phase 1 — Intake & Blueprinting

Whenever the skill is freshly installed or the user commands a new topic (or restarts one), ask the user a set of questions to lay down their customized learning blueprint:

1. Motivation & Goal: What is their stated goal and why are they learning this?
2. Pedagogical Preferences: How spacious/detailed should note explanations be (e.g. detailed with analogies vs. dense)? Do they prefer primary research papers, tool documentation, university portals/lecture slides, teaching portals, blogs, or transcripts?
3. Attached Sources: Have they attached any initial source documents (transcripts, papers, documentation)?
4. Interactive Sandbox Toggles: Do they want companion sandboxes built (only if explicitly requested)?

If the user has attached initial sources, study them immediately, search for similar trusted resources, and use them as the primary curriculum materials to compile best practices.

Write the resolved learning parameters (blueprint) into MISSION.md.

Then judge topic breadth:

• Narrow (fits in one sitting, one coherent mental model): skip to Phase 3.
• Broad (spans real sub-disciplines with their own vocabularies — GNC, immunology, distributed systems): go to Phase 2.

When in doubt, err toward treating it as broad — a wrong breakdown is one confirmation message; a wrongly-scoped single lesson wastes the whole session.

Phase 2 — Breakdown, Frameworks, and Confirmation

1. Map the topic's sub-domains and the dependency order between them — what has to be understood before what makes sense (this is the prerequisite graph; niche topics don't come with one pre-built, so build it explicitly rather than inferring order lesson-by-lesson).
2. Propose the Lesson Frameworks Layout (ordered, numbered syllabus list) aligned with the user's blueprint preferences, explicitly detailing which sections will cite their attached or similar resources. Do not start building lessons yet.
3. Wait for the user to confirm or edit it. If edited, revise and re-present.
4. Once confirmed, write the syllabus into MISSION.md and proceed sub-topic by sub-topic through Phases 3–6, in the confirmed order.

Phase 3 — Diagnostic pretest

Before teaching, run a short generation-based pretest — ask the person to explain, predict, or attempt something, not recognize an answer from options. Recognition tests overestimate readiness; generation exposes the actual gap.

Use the result to set the starting scaffolding level: more worked examples and analogies if the pretest shows a novice, lighter scaffolding and more direct problem-solving if it shows real prior competence. Note this level in the sub-topic's learning-records/ file — it's the input to the fading rule in Phase 5.

Phase 4 — Sourcing

Check references/TRUSTED-SOURCES.md for the topic's field. If the field is covered, research and cite only from those domains, preferring primary sources (papers, standards bodies, official docs) over aggregators. Label any preprint as pre-peer-review.

If the field isn't covered, run the procedure in references/TRUSTED-SOURCES.md under "When a lesson hits a domain not on this list" — propose a shortlist, get it approved, then append it to that file so the next lesson in that field doesn't repeat the work.

Phase 5 — Lesson generation

Build the lesson as a self-contained HTML file per references/lesson-format.md (editorial layout, margin glossary, dual-coded diagrams, real terminology throughout). Two rules that shape the writing itself, not just the layout:

• Generation before explanation. Wherever you're about to explain a concept, ask the person to predict or attempt it first (a "predict before you reveal" block), then explain — even a wrong attempt followed by feedback improves retention more than reading the explanation cold.
• Fade scaffolding as competence rises. Early sub-topics (or a novice pretest result) get more worked examples and analogies. Once learning-records show the person handling a sub-topic's core mechanism correctly, cut the scaffolding for the next one and let them work more from first principles — over-explaining to someone who's already built the schema wastes their time and can interfere with retention (expertise-reversal effect).
• Interactive Companion Sandboxes. Do NOT automatically generate interactive companion sandboxes. Only invoke the companion practice-sandbox skill to build a sandbox if the user explicitly requests it.
• Spacious & Detailed Explanations. Increase the length of lessons and explanation notes. Avoid making them too short, compressed, or dense. Give details space to breathe, pace the content clearly, and use clear structural analogies.
• Expanded Educational Sources. Active search and cite from university course portals, tool documentation, teaching portals, verified scientific blogs, and transcripts in addition to primary research papers, to keep concepts highly accessible.

Use structural (not surface) analogies to things the person already knows where they genuinely clarify a mechanism — and have the person test the analogy's limits rather than taking it as complete.

Phase 6 — Quiz and gap loop

End the lesson with a quiz, per references/lesson-format.md's scoring/gap-report pattern: score computed client-side, wrong answers compiled into a copy-ready gap report formatted as an instruction for the next pass.

• Write the pretest level, quiz score, and gaps to that sub-topic's learning-records/ file.
• If gaps exist, the next lesson pass on that sub-topic re-teaches only the missed concepts — fresh example or diagram, predict-then-reveal again, re-quiz only those — not a full re-teach.
• Hands-on Gap Resolution: If the missed concepts contain manipulable parameters, direct the user to the sibling sandbox (or build one if missing) to resolve the gap through interactive challenge tasks.
• If the topic was broken into a confirmed syllabus, move to the next sub-topic once the current one clears clean (or the user chooses to move on anyway).

Phase 7 — Spaced review (optional — suggest, don't build)

After a lesson or full syllabus is complete, briefly mention spaced review is available: resurfacing taught concepts on a schedule so they don't decay. Suggest running it via a Hermes Agent (Nous Research) cron job, since it can fire unattended and push the review question straight to wherever the person has Hermes wired up (Telegram, etc.) rather than depending on them reopening this chat.

If companion sandboxes were built, sandbox-based challenge tasks (e.g. "reach critical damping") can be queued as spaced review items instead of plain text retrieval questions.

Do not build anything for this unless the person explicitly confirms they want it. If they decline or don't respond, stop at the gap report — no state files, no cron job, nothing left half-configured.

If confirmed, follow references/spaced-repetition-hermes.md to set up the per-concept state file and the cron job.

---

Notes on tone

Write and speak to the person as a competent adult who wants real fluency, not a simplified summary. Don't hedge technical claims with "roughly speaking" once a term has been properly defined — use it precisely from then on, the way a professional in the field would.