Learner Tracking

Understanding the learner

Record what happened precisely enough that another teacher can make the next decision. “Bad at math” is useless. “Cancelled x across addition, corrected it after comparing x(x+1) with x²+1” tells the next teacher what to check.

Read and write

For someone you already know, use the script beside this skill:

python3 skills/learner-tracking/scripts/learner_state.py init alex
python3 skills/learner-tracking/scripts/learner_state.py summary alex
python3 skills/learner-tracking/scripts/learner_state.py record alex --event session.json

init creates a blank learner profile (learners/<name>/state.json). It starts completely empty — do not guess or assume the user's name, background, or skill level. By default, profiles are saved in the repository's ignored learners/ directory. Pass --root <directory> to use a different folder (e.g., in automated tests). For the full schema and update rules, see references/evidence.md.

When enrolling a learner, the validated course plan is copied to learners/<id>/courses/<course-id>/course.json. The learner's state.json only stores a relative path, revision number, and fingerprint (hash) of the course plan rather than keeping a duplicate copy. If the course plan changes and its hash no longer matches state.json, future updates are blocked until the plan is reconciled. If you are working with an older record that has an embedded plan, run migrate-courses <id> once to convert it safely.

Never render lessons, viewer pages, or progress directly from a blueprint course.json. Always set up the learner first:

1. Identify the learner: If they provide a name, convert it to a lowercase folder name (e.g., alex). If they don't, proceed automatically as learner and say: "I'll save your progress under 'learner' — tell me a name anytime to make it yours." Never ask the user for a "learner ID".
2. Initialize and enroll: Run init followed by enroll --course <course.json>. Omitting the name defaults to learner.
3. Verify: Confirm that learners/<name>/courses/<course-id>/course.json exists before recording attempts, summarizing progress, or rendering views.

Course and memory categories

Read references/memory-categories.md when starting, resuming, enrolling, or finishing a course. Store a validated course with enroll <id> --course <course.json>. Use complete-course <id> --course-id <slug> when the learner finishes; the script produces a chapter-by-chapter curriculum with topic names, teachers, sources, assessments, and actual evidence.

Read references/adaptive-lifecycle.md to adapt in real time: record what the learner does, then tell the course skill to update the plan when a source fails or the learner is stuck.

Every recorded attempt or topic transition refreshes profile, course, topic, teaching-observation, and next-step memories. Update at meaningful evidence changes during the conversation, not only at the end of a course. On resumption, use earlier taught topics as explicit bridges into the next topic. Keep one folder per person; do not assume unrelated chats have shared memory.

Resolve every enrolled plan before changing learner state. If a referenced plan is missing, stale, or invalid, fail before recording a new attempt or profile change. Derived Markdown views may be rebuilt from valid state; they never override it.