Drill

Contract

Field	Bound contract
Trigger	give me an exercise, quiz me, keep it fresh, what am I missing / where are my gaps, or explicit practice/quiz/recall/probe
Authority	Reversible local: writes only PROGRESS.md at the workspace root; rollback is deleting the lines this run appended. No remote mutation. The file is append-only, never rewritten.
Side effect	Appends one line per attempt to PROGRESS.md at the workspace root; drives spaced recall and probes gaps.
Done	The named move completed; every attempt recorded; cleared concepts marked no-hints-independent.

Inputs

• A concept name (required) and a move (optional): practice, quiz, recall, or probe.
• The move is optional: the routing table picks it, an explicit argument overrides, and no match defaults to practice.
• Optional: item count for quiz (default 5–8).
• probe requires CORPUS.md at the workspace root. recall requires prior PROGRESS.md history. State which is missing rather than inventing it.

Procedure

1. Read PROGRESS.md at the workspace root (create it on first write) and, for probe, CORPUS.md. If neither PROGRESS.md nor CORPUS.md exists, say once that nothing is being recorded, ask which concept to work on, and run in-session only. Done when: PROGRESS.md is read or confirmed absent, and for probe, CORPUS.md is read or confirmed absent.
2. Pick the move. An explicit argument overrides the table; no match means practice. Table: "give me an exercise" / "let me practise X" / "walk me through one" → practice; "quiz me" / "test me on X" → quiz; "what should I review" / "keep it fresh" → recall; "what am I missing" / "where are my gaps" / "am I ready for X" → probe. Done when: the move is picked and stated.
3. Run one move per run. Another move is another run. Done when: one move is selected for this run.
4. practice: three rungs in this order, one rung per run: worked (the agent solves it and narrates why each step is taken; done when the full solution is narrated and the learner has answered one self-explanation prompt); faded (the agent solves everything but the last step and the learner finishes it; each further faded run removes one more step, always from the end backward, so the learner performs the final step every time; done when the learner has produced the step the rung asks and the attempt is recorded); independent (the learner solves it whole; done when the learner has produced the step the rung asks and the attempt is recorded). Advance a rung only when the current one was cleared without hints. Done when: the current rung is completed and recorded.
5. quiz: five to eight items unless the user asks for a different count, mixed between recall and application, over concepts already explained or cleared. The learner commits to an answer before anything is revealed. Done when: every item is graded and each miss names the misconception it reveals.
6. recall: a concept is due on an interval ladder counted from the date its independent rung was cleared: 1 day, 3 days, 7 days, 21 days, then every 60 days. Due means today is at or past the next interval with no retrieval recorded since. A missed retrieval resets that concept to the start of the ladder. Interleave across cleared concepts only. Two consecutive misses on one concept send it back to a faded rung. Done when: every due concept has been retrieved once and recorded.
7. probe: take what the learner says they want to do next, walk CORPUS.md back through the concepts it needs, ask one discriminating question per concept, then rank the confirmed gaps by how many downstream concepts each blocks. Done when: the ranked list is reported and every confirmed gap is recorded.
8. Hints: three tiers, released one at a time and on request: nudge (names the concept in play, no structure); strategy (the shape of the solution, no answer); bottom out (the step itself). Once a concept's independent rung is cleared with no hints, withdraw hints for that concept. Done when: hints are released on request and withdrawn for cleared concepts.
9. Grading: name the specific misconception an answer reveals rather than scoring it right or wrong. Say what the answer got right before what it missed. Release the solution once the learner has committed to an attempt. Done when: each answer is graded with its misconception named and the solution released.
10. Record every attempt in PROGRESS.md with this line shape: - <YYYY-MM-DD> · <move>[/<rung>] · <cleared|missed>, hints <none|1|1-2|1-3>[, <misconception>]. A concept is cleared when its practice/independent line reads cleared, hints none. Missed concepts are not cleared. Use the words rung and cleared and no synonyms. Done when: every attempt is recorded in PROGRESS.md with the correct line shape.

Failure and recovery

• No PROGRESS.md and no CORPUS.md: say once that nothing is being recorded, ask which concept to work on, and run in-session. Do not create files for a probe that needs CORPUS.md.
• probe without CORPUS.md: blocked. Report the missing file; do not invent gaps or rank an empty list.
• recall with no cleared concepts: nothing is due. Report that and stop; do not fabricate a due set.
• Rung not cleared: do not advance. Record the miss with its misconception; do not rewrite PROGRESS.md (append only).
• Hints used on an independent rung: that concept is not cleared; record hints 1 through 1-3 as used.
• Rollback: PROGRESS.md is append-only; recovery is deleting the lines this run appended. Never swallow a miss or mark cleared when hints were used.

Output

One completed move plus one appended PROGRESS.md line per attempt (or in-session only when no files exist), with the rung outcome for practice, graded items for quiz, due concepts retrieved for recall, or a ranked gap list for probe.