How the grading engine works

Answers update three things: your understanding of a concept, when it returns for review, and your project’s progress toward harder questions. An enforced session also counts eligible passes toward its commit gate.

Concepts and the graph

A concept is an idea identified by a lowercase hyphenated slug, with a domain, tier and optional prerequisite relationships. Built-in domains are web-auth, react, node-backend and git. Concept packs and the agent can extend the graph; new agent-created concepts are capped by max_new_concepts_per_session (eight by default).

The planner orders prerequisites before dependent concepts and reports missing foundations. It selects a question tier within your project’s level.

Grading: the 0–5 scale

Grade	Meaning
0	No answer, recorded separately as “I don’t know” or a decline.
1–2	Incorrect.
3	Correct with difficulty; the minimum passing grade.
4	Correct.
5	Correct with an explanation of why.

A multiple-choice selection is capped at 4. A written explanation through “Other” can be assessed beyond recognition alone. Declining a question is distinct from not knowing: a decline is dropped without teaching, while “I don’t know” leads to an explanation and can support a later follow-up. Declines do not count against promotion accuracy.

With explain_on_wrong on (the default), wrong or unknown answers also start a background explainer page. The verdict arrives immediately; the quiz does not wait for the page. Skips and declines do not create one.

Who grades in the side panel

The experimental quiz side panel records an answer through the same code as a card answer: the 4 ceiling for a pick, declines, dont_know, promotion and the gate all apply unchanged. What differs is who produces the grade. When the model writes a panel question it gives each option a grade (4 for the right one, 2 for a distractor with the shape of the idea, 1 for one built on a misconception), and a pick takes that grade; a hesitant 3 is reachable only through typed words. Words typed under Other are graded by one model call from the panel, on this page’s 0 to 5 scale, with no conversation history. An unreadable verdict records nothing; the panel keeps your words and shows a Retry button. Skip question records a decline. New to me — Teach me records dont_know with grade 0, so it weighs like a miss, and it always starts the explainer page.

Correcting from an explainer

When the tutor records a multiple-choice question it also stores the right option (correct) and the note under each option (option_notes). After reading the explainer for a missed question, you can pick again from the dashboard:

Pick	What is recorded
Wrong	The pick, as a numbered try. Nothing else: the miss already cost the grade.
Right	The pick, plus a new answer at grade 3 that updates the concept’s score and review date like any pass.

The original miss is kept unchanged, but from then on it counts as right: in the dashboard’s accuracy (overall, per project and per session) and toward a level’s passing answers and accuracy, while the number of answers stays the same. Fixing a mistake is learning, and accuracy that could never recover from early misses only discourages. The correction still does not count toward a commit gate, a level’s distinct concepts, or clearing the review backlog: choosing the answer straight after reading it is recognition, not recall, so the concept still returns for review. Each miss can be corrected once. A question recorded without its right option, including everything recorded before this feature, cannot be corrected.

What a miss or a blank earns depends on who asked. The tutor is instructed to give an automatic question (a checkpoint or the end-of-task sweep) the verdict, the right answer and one line of why, then resume the work with no follow-up question; a quiz or lesson you asked for may ask one narrower question first, and a blank there gets the full four-step lesson.

Why the questions are multiple choice

Questions offer four options so you can respond while working. Exactly one option should answer the question; the other three are meant to be believable but wrong. The plan assigns the correct answer’s position to avoid always putting it first, and the tutor is instructed to write the three wrong options, insert the right one at that position, then re-read the list to confirm it is in that slot; a question with the right answer in the wrong slot counts as a failed question. The four options and the neutral one-line description under each are written to similar visible lengths, label and description together, so the right answer cannot be spotted by being the longest or the most carefully explained. A description never says why an option is right or tempting; that reasoning comes after you answer. Before a question is shown, the panel and the ask-label hook check this: an option that outruns the next by a few words, or a description that explains itself, sends the question back to Claude once to be rewritten, and a question that comes back with the same wording is shown as written. Each send-back, and whether the rewrite still tripped the check, is counted in option_checks on your machine (the outcome and session only, never the options); nothing that scores or gates reads it. “Other” lets you say you do not know or give an explanation in your own words.

Questions are written for someone who has not read the code: a background agent often writes it, so the tutor is instructed to explain any project-specific name in a sentence of setup before the question, and to key the answer on the concept rather than on something only Claude saw. If a question still leaves you without enough context, or two options both answer it, say so through “Other”. The tutor is instructed to own the mistake, give the answer with one line of why and record the question as invalid, never as “I don’t know” or a decline. An invalid question is set aside in its own table: it grades nothing, so it cannot lower mastery, accuracy or your level, move a review date or count against a commit gate, and the same wording is not asked again. Only an answer you actually gave, or a real “I don’t know”, is graded.

If another option also answers the question, pick it or say why through “Other”. The tutor is instructed to grade a defensible answer as correct and to say the question had two right answers, so a flawed question should not lower your mastery.

Scheduling: SM-2

SM-2 is a spaced-repetition method: passing a review increases the delay before the concept returns.

State	Rule
First passing recall	Review in one day.
Second consecutive passing recall	Review in six days.
Later passing recalls	Multiply the previous interval by the ease factor, capped at 3,650 days.
Failed recall	Reset consecutive repetitions and review in one day.
Ease factor	Starts at 2.5, adjusts after each grade, never below 1.3.
Mastery	Score at least 0.7, four passing answers in a row, passes on at least two different days (UTC), and at least one pass on a question of tier 2 or higher. A failed answer restarts the count.

The score is a recency-weighted average of the last five grades, normalised to 0–1; each newer grade has weight 0.6. The score alone does not make a concept mastered. You also need four passing answers in a row, on two different days, with one above tier 1, so answering every question in one sitting does not master a concept. A correction after a miss counts toward the four passes but does not raise the highest tier passed.

For overdue concepts, the displayed score decreases by 0.05 per complete week, stopping at 0.3 without raising a score already below that floor. This is calculated when reading the record, not written over your history.

How repetition is reduced

Mastered concepts normally return only when the current work touches them while their review is due. From earlier sessions, only questions you declined, did not know or got wrong come back, once their review date arrives; a correct answer never comes back that way. The planner supplies recent question history so Claude can choose a new angle, and a concept answered in the current session is ordinarily removed from that session’s plan.

An unmet enforced gate takes priority: it can ask about mastered work concepts and retry a concept you did not know after teaching it. A retry uses a different question at a lower tier, within the project’s band. If automatic questions have used the session budget, /eklavya:quiz can request another round of eligible questions. Repeated question text is flagged when an answer is recorded; the answer is still saved, and wording alone cannot guarantee a new angle.

Where each hook fits

Event	Responsibility
SessionStart	Load the learner profile and project memory, initialise the session and give logging instructions.
UserPromptSubmit	Capture your prompt, recall relevant memory, occasionally remind the agent to log concepts when it has not and, with delegate_work on, add the delegation request next to a task-sized prompt.
SubagentStart	Give delegated agents the logging instruction when questions are on, and point them to project memory when it has entries; they contribute to your session without quizzing you.
PostToolUse	Capture tool activity; eligible concept-logging and work calls can trigger a checkpoint question; with delegate_work on, the first time the main conversation changes a second file (through an edit tool, or a shell command in this repository or in the worktree a leading cd <dir> && named), remind Claude once to delegate the rest, unless it has already started a building agent.
Stop	Process memory and offer the remaining learning work, respecting cadence, spacing and session limits.
PreToolUse	Under enforcement, block recognised git commit commands until the gate passes. Before a Read, add the file’s past work from memory.

Hook failures do not break the coding session. How it works shows the full sequence; Configuration lists the limits.