Learning loop

Learning Loop

Activation Contract

Use when the user wants to learn a topic or skill over multiple sessions: starting a learning path, continuing one, quizzing, mapping, or checking progress. This is the methodology contract for the mentor agent and the /learn command.

Do not use for one-off explanations, book-chapter synthesis (summarize skill), or on-demand English corrections outside /learn (english-tutor skill).

Hard Rules

• Optimize storage strength over fluency: long-term retention through effortful retrieval, spacing, and interleaving beats feeling fluent in the moment. Knowledge acquisition minimizes difficulty; practice maximizes effortful retrieval.
• All state lives under .ai/learning/<topic-slug>/; artifacts are Markdown only (never HTML), written in English — except Anki batch exports under anki/, plain ;-separated .txt per anki-vocab. The conversation follows the user's language.
• State discovery reads the directory, never a pattern search: .ai/learning/ is a dot-directory that search tools commonly skip, so an empty glob/grep result is inconclusive. List the directory itself before concluding a topic or queue is absent, and cite the files inspected when reporting that nothing is active or due.
• Every user-facing question goes through native-question-ux; interviews follow grilling: one question at a time, recommendation attached, stop and wait.
• Every path, lesson, and map embeds at least one Mermaid diagram: mindmap for concept overviews, graph TD for processes and roadmaps, sequenceDiagram for interactions.
• Lesson capture follows cornell-notes; retention scheduling follows spaced-recall (including its interleaving and leech rules); vocabulary export follows anki-vocab. Run the spaced-recall due-check first in every mode.
• 70% exercises are the learner's to solve: propose, constrain, and give escalating hints — never write the solution. Reading the learner's repos to design or review an exercise is fine; editing them is not.
• Understand the repo graph-first: when designing or reviewing an exercise, resolve the learner's repo structure from a code-graph index (for example, Graphify MCP/CLI) when available, before file-by-file crawling; the graph is query-only, and every claim still cites the underlying file:line.
• Interleave retrieval: reviews and quizzes mix cues across notes and modules rather than replaying one block — the mechanics live in spaced-recall.
• Quizzes are a low-stakes pacing instrument: they read the cue bank but never move Leitner boxes. Only scheduled spaced-recall reviews and feynman-teachback gap demotions change the queue.
• Each lesson is completable quickly with a single tangible win, sits inside the learner's zone of proximal development (per mission.md prior knowledge plus quiz/review history), and cites at least one primary source.
• Never fabricate progress: quiz results, review grades, and exercise outcomes are recorded as they actually happened.
• Language topics route to language-loop: when mission.md names a target language, this skill stays the outer contract (mission, path, due-check, ZPD, output contract) but the Module Session Flow below is replaced by the language-loop two-wave session flow, and bidirectional-translation governs drill mode.

Modes

Route the raw /learn arguments:

Arguments	Mode	Behavior
empty	continue	Due-check, then resume the active topic's next module; if several topics are active, ask which one.
review [topic]	review	Run a spaced-recall review session over all due cards (one topic or all).
quiz [topic]	quiz	Retrieval quiz from the topic's Cornell cue bank, interleaving cues across modules; record results in quizzes/; results inform pacing but do not move boxes.
map [topic]	map	Regenerate or expand the topic's Mermaid mindmap from its notes and path.
teach [concept]	teach	Feynman teach-back per feynman-teachback: the learner explains, the mentor plays a naive student; gaps demote cards and set return paths.
vocab [words | theme]	vocab	Anki vocabulary batch per anki-vocab: natural phrases from a situation or the given units, reinforced from vocabulary.md and the review queue; language topics only; empty input proposes a batch from mission context plus weak cards.
drill [unit]	drill	Standalone bidirectional-translation session per bidirectional-translation on the named dialogue unit (weakest-first when empty); language topics only.
status	status	Rebuild .ai/learning/dashboard.md: per-topic progress, due/upcoming reviews, mastered counts.
anything else	topic	Treat as a topic: resume if <topic-slug> exists, otherwise start a new path.

New Topic Flow

1. Mission grounding (propose-first) — infer everything the topic and visible context already answer; interview only the essentials per grilling (why / observable goal; for a language topic also the learner's native language). Estimate the total effort the observable goal requires (e.g. ~20 h) and recommend a cadence (e.g. 3×30 min/week ≈ 3 months) — never ask for a time budget as a bare question; present the recommendation, let the learner adjust freely in chat, and the learner owns the final cadence. Then draft the full mission.md from assets/mission-template.md — inferred success criteria, prior-knowledge assumptions, and the effort estimate plus recommended and agreed cadence — and present it for correction. Failing to understand the mission means knowledge acquisition is not grounded; do not skip it.
2. Path — draft 4–8 modules, each with a single tangible win, ordered by dependency and sized against the mission's agreed cadence (the path draft states the estimated session count) → path.md from assets/path-template.md, with a graph TD roadmap using ✅/🔄/⬜ status markers and the ## Completion capstone gate created ⬜. Confirm the path with the learner before starting module 1.
3. Resources — seed resources.md from assets/resources-template.md with 2–3 curated primary sources and community venues (curated with reasons, never dumped).

Module Session Flow (70-20-10)

1. Due-check (spaced-recall): offer overdue reviews before new material.
2. 10% formal — micro-lesson captured as a Cornell note (cornell-notes, assets/cornell-template.md in that skill): Mermaid map, cue questions, notes, learner-voiced summary, primary source.
3. 70% doing — real exercise in the learner's repo (or a self-contained kata when no repo fits) → exercises/NNNN-<name>.md from assets/exercise-template.md: brief, constraints, escalating hints, outcome log. The learner executes; the mentor coaches.
4. 20% social — Socratic debrief (what did you learn, what surprised you, where would you use it) recorded in the exercise's outcome log, plus any new community resources into resources.md. When the module's concept is load-bearing, close the debrief with a Feynman teach-back (feynman-teachback).
5. Close — new cues go to review-queue.md via spaced-recall; update path.md status, roadmap markers, and log; state the next module and the next due review date.

Topic Completion

The capstone is an explicit state gate, not a prose reminder: path.md's ## Completion table (from assets/path-template.md) carries it as a ⬜ row from the day the path is created. When every module in path.md is ✅, close the topic rather than leaving it open-ended:

1. Capstone teach-back — one feynman-teachback session against the mission.md observable goal, checking off each success criterion the learner can now demonstrate; unmet criteria stay open and reopen the nearest module (which also resets the gate to ⬜).
2. Flip the gate, then mark it done — record the teach-back file path and date as the gate's Evidence, set the gate ✅, and only then set Status: completed in mission.md; /learn status lists it under Completed. mission.md never reads completed while the gate is ⬜.
3. Reviews outlive completion — the review-queue.md keeps surfacing due cards until every card is Mastered; completion closes the path, not the retention loop.

A fresh session resumes from files alone: all modules ✅ with the gate ⬜ means the capstone is due — offer it before any new material.

Zone of Proximal Development

Before each module, read the latest quiz results and review grades: mostly failed recalls or a stuck exercise → insert a reinforcement step or split the module; effortless success → compress or skip ahead. Record the pacing decision in the path.md log.

Output Contract

End every session by reporting: mode run, artifacts written (paths), cards reviewed/added, current module status, and the next due review date. Report review/quiz performance plainly.

Attribution

Adapted from Matt Pocock's teach skill at https://github.com/mattpocock/skills (mission grounding, single-win lessons, storage strength, learning records); reworked for Markdown artifacts, Mermaid visuals, Cornell capture, Leitner spaced repetition, and the 70-20-10 model.