Gordito

View saved version →

---
name: generate-quiz
description: Build a daily vocabulary quiz for a Gordito learner from the words their spaced-repetition schedule says are due, using what you already know about them.
---

# Generate a quiz from due vocabulary

Gordito stores the record; you supply the judgement. The server decides **when** a word
comes back and you decide **what the question looks like**. Never invent a review
schedule, and never quiz a word the server did not return as due.

## The loop

1. `get_enrollments` — pick the enrollment. If there is none, the learner has not finished
   signing up: send them to the sign-up page to choose their language. You cannot create an
   enrollment yourself, and you should not try.
2. `get_vocabulary` with `dueOnly: true` — this is the entire pool of words you may quiz.
   If it returns nothing, say so and stop; do not invent words to pad a session.
3. `generate_quiz` — each question naming the `vocabularyIds` it tests.
4. Wait. The learner answers in the card and it submits for you.
5. `grade_questions` — one call for the whole quiz, scoring every word each question
   tested, honestly.

## Writing the questions

Write the prompt in the learner's **origin** language and ask them to produce the
**learning** language. Production is the point: recognition is what they can already do.

**Draw on what you know about them.** This is the reason Gordito is worth using instead
of a flashcard app. If they have been talking to you about Formula 1 all week, set the
sentence at a race. If they mentioned their in-laws are visiting, use that. A word met in
a sentence that matters to the learner is a word that sticks.

Vary the shape across a session so it does not read as a drill:

- **Translate a sentence** — the default. Embed the due word in a natural sentence.
- **Complete the gap** — give a sentence in the learning language with the word removed.
- **Answer a question** — ask something whose natural answer needs the word.

Rules that matter:

- **Name every due word the question tests** in `vocabularyIds`. A question without any is
  rejected: the review would not count and the word would stay due forever. One word per
  question is the usual shape and the easiest to grade honestly, but a sentence that genuinely
  exercises two due words may name both — each is scored separately afterwards, so you are not
  forced to average them. Never list a word the prompt does not actually test just because it
  is due.
- **Never put the answer in the prompt.** Do not write the learning-language word, and
  avoid a cognate so transparent that no recall is needed.
- **Keep prompts to one sentence.** You are testing one word, not reading comprehension.
- **Use the example sentence as a hint of register**, not as the prompt itself — quizzing
  the sentence they were taught tests memory of the card, not knowledge of the word.
- **Cap a session at 10–15 questions** even when more is due. A session someone finishes
  beats one they abandon; the rest stays due tomorrow.

## Grading

Score on the FSRS rating scale, and be strict — this feeds the scheduler directly:

| Score | Meaning |
| --- | --- |
| 1 Again | Wrong, blank, or the wrong word entirely. **Requires at least one recorded error.** |
| 2 Hard | Right, but laboured, hesitant, or awkwardly phrased. |
| 3 Good | Right. |
| 4 Easy | Right, immediate, and idiomatic. |

A generous grade is not kindness. Marking a shaky answer `3` tells the scheduler the
learner knows that word, and they will stop seeing it precisely when they most need to.
If the answer would not pass with a native speaker, it is not a 3.

**Mark the whole quiz in one call.** `grade_questions` takes every question you are
marking. The batch is written together or not at all, so if one grading is rejected nothing
lands — you fix it and resend, rather than discovering half the quiz is marked and half is not.

**Write the marking in the language being learned.** `correctionNote` and every error `rule`
go in the 

Preview of the first 4,000 characters. Read full instructions →