a2learn primitives: the exhaustive pedagogical vocabulary, and the build plan

[adamstankiewicz]

The middle tier of #98, planned end to end. Two rules govern everything below:

1. Pedagogically correct: every primitive is grounded in a named, evidence-based learning pattern (citation in the vocabulary table) — UI convenience alone never adds a word.
2. Implementation is prover-gated: a primitive merges only when a real registry kind composes through it (labels are earned). The exhaustive vocabulary is spec'd up front; code lands prover by prover.

Exhaustiveness test: all 16 registry kinds must decompose into the vocabulary. They do (table below) — a kind that can't decompose means a missing word, not a forced fit.

The vocabulary

Atoms — content & encoding support (never interactive, no verdicts)

Primitive	Params	Pedagogy	Prover
Text	markdown (basic catalog)	—	shipped (basic)
Callout	intent, label, text	emphasis/admonition (DITA taxonomy)	✅ shipped
Content	src, mediaType, transcript, caption	dual coding (Paivio; Dunlosky et al. 2013)	narrated-card
Term	label, definition, revealMode	vocabulary anchoring	flashcard fronts; glossary future
Example	content, fadeSteps	worked examples + fading (Sweller; Ge et al. 2012)	step-reveal spec upgrade (own issue)
Source	passage, attribution	evidence-grounded argument (cite-the-text)	defend-claim, draft-meter passages

Molecules — behavior, policy-parameterized

Primitive	Params	Pedagogy	Verdict	Prover
Sequence	order, disclosure, revealed (+later: branching, spacing/interleave schedule)	scaffolded progression; interleaving (Rohrer)	inherits	✅ shipped
Reveal	faces (+later: trigger click|prerequisite, hint-ladder)	retrieval structure; hint escalation	none	✅ shipped
Check	prompt, responseType, feedbackMode, confidence?	formative retrieval practice (Roediger & Karpicke); calibration	formative — never transcript	low-stakes uses of assessing kinds
Response	type (choice|text|extended-text|numeric|expression|match|order|hotspot|drawing), cardinality, scoring (pre-authored)	assessment; collapses QTI 3.0's ~20 interactions	summative — declared	drag-sort (order), drag-categorize (match), swiper-flashcard (choice), timeline-builder (order), draft-meter (extended-text via a2learn.score), draw-the-curve (drawing), crossword (gap-text)
Elaboration	prompt, targetConcept, support	self-explanation / elaborative interrogation (Chi; ICAP Constructive)	optional rubric	find-the-flaw's diagnose-why; step-reveal upgrade
Interaction	tool, constraints, feedback	discovery/manipulatives (ICAP Active→Constructive)	none by design	fraction-area-model
Dialogue	turns policy, role, closure	ICAP Interactive — deepest tier	via embedded Check/Response	debate-ai, writing-workshop
Reflection	prompt, scale/goal	metacognition/SRL (Zimmerman)	never	no prover yet — waits for one

Full decomposition of the registry (the exhaustiveness proof): markdown-card=Text+Callout ✅ · flashcard=Sequence+Reveal ✅ · step-reveal=Sequence(gated)+Callout ✅ · narrated-card=Sequence+Content · swiper-flashcard=Sequence+Response(choice) · drag-sort=Response(order) · drag-categorize=Response(match) · timeline-builder=Response(order,time) · crossword=Response(gap-text) · fraction-area-model=Interaction · draw-the-curve=Response(drawing)+Check · draft-meter=Source?+Response(extended-text) · find-the-flaw=Sequence+Response(choice)+Elaboration · defend-claim=Source+Response(extended-text)+Elaboration · debate-ai=Dialogue · writing-workshop=Dialogue+Response(extended-text)

Cross-cutting contracts: assessmentType: summative|formative forced by schema wherever a verdict exists (invariant 3 as schema, not convention); scoring pre-authored, never model-generated at render time; anonymous ids only in any event payload (invariant 2); ICAP tier as planner-guidance metadata on every primitive (not schema).

Phases

• 1 — Harden what shipped (no new words): zod schemas for Sequence/Reveal/Callout; conformance gains a composition layer — validate primitives surfaces against those schemas, golden per composed kind, negative controls. Unblocks trusting everything after.
• 2 — Content (verdict-free, prover ready): narrated-card composes as Sequence+Content(audio, transcript); renderer view; three-tier demo row.
• 3 — Check + Response (blocked on a2learn interaction contract: a standard event/function vocabulary for registry widgets #99): the verdict contract must exist first. Then: Response schema with the QTI-collapsing type enum; provers drag-sort → swiper-flashcard → draft-meter (extended-text through the a2learn.score function); evidence events per a2learn interaction contract: a standard event/function vocabulary for registry widgets #99; assessmentType enforcement with negative controls proving a verdict-free primitive cannot emit one.
• 4 — Constructive tier: Elaboration (find-the-flaw prover), Dialogue (debate-ai prover), Interaction (fraction-area-model) — with an explicit per-kind decision recorded where a manipulative's essence resists parameterization (whole-widget tier is the honest answer there, not a forced primitive).
• 5 — Atoms completion + policy growth: Term, Source; Example via the step-reveal fadeSteps spec upgrade (own issue — contract change); Sequence branching + spacing/interleaving policies; Reflection stays spec-only until a prover exists.
• 6 — Catalog formalization: versioned catalog document + served schema + vendoring rules + two-direction conformance. This is the milestone that un-drafts docs: the a2learn format draft #74.

Ordering rationale: verdict-free before verdict-carrying (contract risk isolated to phase 3), provers-in-hand before spec-only, formalization last so the catalog freezes after the vocabulary has been exercised, not before.

Relations: the vocabulary lives under #98; verdict semantics join at #99; phase 6 un-drafts #74. Research base in #98 (comment).

🤖 Generated with Claude Code

[adamstankiewicz]

Correction (Adam): primitives are a generative substrate, not a projection layer

The prover-gating rule above is wrong as the main line. Primitives don't exist to re-express existing registry kinds — they can lead to new widgets entirely: a planner composes a novel activity from the vocabulary at generation time, and that composition is the widget. The registry decomposition table demotes from merge-gate to coverage evidence (it still proves the alphabet is sufficient for everything we already know how to teach).

What this adds to the plan:

The composed kind — one registry entry, infinite activities

A single new widget kind whose spec IS a primitive tree:

• Spec: zod schema of the composition (primitives + policies + basic-catalog content), recursively validated. Invariant 1 intact — the model emits a data tree, human-written schema validates it, human-written primitive renderers draw it.
• Generator: prompts the planner with the vocabulary + its pedagogy metadata (ICAP tier, when-to-use guidance from the research base) and emits a composition. Pedagogical correctness moves from "which kinds exist" to generation-time guidance + schema constraints — the vocabulary's citations become the planner's style guide.
• Renderer: the primitives renderer, which already exists in draft.
• assesses is derived, never asserted: computed from the tree — contains a Response/Check with declared scoring ⇒ may claim measurement; otherwise assesses: false by construction. Invariant 3 becomes structurally impossible to violate in generated activities.
• Scoring in compositions: declarative answer keys ride in the tree (executed by human-written check code), or server-run scoring via the a2learn interaction contract: a standard event/function vocabulary for registry widgets #99 a2learn.score function. Never model-judged at render time without declaration.

Re-sequenced phases

1. Harden shipped primitives (unchanged — schemas + conformance composition layer; now load-bearing for generation, not just demos).
2. Content + remaining verdict-free words (unchanged).
3. composed kind, exploration-only: generator + schema + renderer for verdict-free compositions (Sequence/Reveal/Callout/Content/Term/Elaboration-unscored). New activities exist that no React kind describes. Pathway integration honest: composed steps are exploration until phase 4.
4. Check/Response with a2learn interaction contract: a standard event/function vocabulary for registry widgets #99's verdict contract → composed activities gain measured steps, assesses derivation goes live.
5. Constructive tier + policy growth (unchanged, but provers optional — a primitive may merge on the strength of generated use).
6. Catalog formalization (unchanged; un-drafts docs: the a2learn format draft #74).

The gate that remains: pedagogical grounding (a word enters the vocabulary only with its evidence base) and verdict hygiene as schema. The gate that falls: waiting for an existing kind to need it.

🤖 Generated with Claude Code

[adamstankiewicz]

Candidate novel primitives (post-Check/Match/Hunt brainstorm)

The local stateful tier proved out (Check, Match, Hunt shipped in #101). Next candidates, ranked by pedagogy × novelty × implementability — all renderer-local, verdict-free, generic:

1. Estimate — commit a value on a slider before seeing the actual, then the reveal shows both and the gap. {prompt, min, max, unit, actual, feedback}. Grounding: prediction + the hypercorrection effect (Butterfield & Metcalfe) — confident wrong guesses, corrected, stick hardest; committing first is what makes the reveal teach. Works everywhere numbers live (science, stats, history magnitudes). The most novel of the set — no QTI/H5P equivalent commits-then-reveals without grading.
2. Anticipate — the student types their own short list ("what do you think the three causes were?"), then reveals the expert list beside theirs for self-comparison. No scoring, no transmission — the typing stays in the widget. Grounding: the generation effect (Slamecka & Graf) — generating beats reading even when the generation is wrong. First free-text primitive, and invariant-safe because nothing judges or records it.
3. Branch — a Sequence policy extension: a node can carry options that route which child comes next; the path taken is local state. Grounding: agency/consequence in scenarios (H5P's Branching Scenario, situated learning). Ethics dilemmas, historical decisions, debugging trees — and it's policy data, not a new component.
4. Cloze — word-bank gap fill, tap-based: {textWithGaps, bank: [words + distractors]}. Grounding: retrieval in context; QTI gap-match's one genuinely great idea, mobile-friendly without drag.
5. Model — a discrete micro-sim: 1–2 variables with option values, a model-authored outcome table, the student flips inputs and watches outcomes change. {variables: [{name, options}], outcomes}. Grounding: ICAP-active manipulation and mental-model building — the composable cousin of fraction-area-model. Constrained to small truth tables so the model authors it honestly.
6. Check gains confidence — a sure/unsure tap before the answer locks. Not a new primitive, one knob: calibration metadata for the learner's own eyes (hypercorrection again).
7. Order — tap-to-sequence with local check; cheap, but overlaps native drag-sort — build only when a composition needs inline ordering.

Line unchanged: all of these keep state and feedback inside the component; the moment any answer should count as evidence, that's Response behind #99.

🤖 Generated with Claude Code

[adamstankiewicz]

Brainstorm round 2 — and a cost-tier insight

New pedagogy enters the alphabet at three costs, and the vocabulary should exploit all three:

• Patterns (prompt-only, zero renderer code): named recipes the generator instantiates from existing primitives.
• Policy knobs (a parameter on an existing renderer).
• Primitives (new renderer — the expensive tier, reserve for genuinely new mechanics).

Patterns (free — generator guidance only)

• Predict–Observe–Explain (White & Gunstone): Check (commit) → Reveal (observe) → why-Callout / Elaboration (explain). Composable today.
• Worked example → fade: full example, then the same structure with later steps as Checks (Renkl's fading). Composable today.
• I do / we do / you do: gated Sequence of demonstration → guided Check → solo Check.
• Anchored intro: concrete scenario hook before any content (CTGV anchored instruction).

Policy knobs (cheap)

• shuffle / sample: n on Sequence — variability of practice; draw 4 of 7 authored items, different per student.
• respace on Check — the same Check re-surfaces near the end of the sequence (lag effect; within-activity spacing).
• streak on Sequence — a run counter across contained Checks; motivation mechanics without points-shaming.
• confidence on Check (round 1) and two-tier Check: after answering, a second tier asks which reason — the misconception-diagnostic item format (Treagust). Tier 2 is options+feedback, same renderer bones.

New primitives (the earn-a-renderer tier)

• Place — put items on a continuum (a century line, an acidity scale), then reveal actual positions and gaps. Estimate generalized to sets; calibrated ranking. {axis: {min, max, label}, items: [{text, actual}]}. Nothing in QTI does magnitude placement with self-reveal.
• WhichOne — Which One Doesn't Belong, math-ed's anti-quiz: four items, every answer defensible — tap any, get the reason it could be the odd one. Celebrates argument over answer-getting; ICAP-constructive. {items: [{text, reason}]}.
• Tag — annotate a passage by tapping segments and assigning tags (claim / evidence / reasoning; metaphor / simile). Multi-class Hunt; close-reading and CER practice as data. {segments, tags, key}.
• SpotDifference — two near-identical texts/expressions/code snippets; find what changed and why it matters. Error discrimination, proof-reading, equation-step auditing. {a, b, differences}.
• Notation (atom) — proper math/chem rendering (KaTeX) so compositions can speak mathematics; unlocks every math topic for the alphabet.
• Contrast (atom) — two labeled cases side by side with a comparison lens (Schwartz & Bransford's contrasting cases: comparison prepares learning before telling).

Excluded on purpose: timers/speed pressure (anxiety without learning), muddiest-point exit tickets (that data wants to reach the teacher — it is evidence, so it waits for #99), model-authored diagrams (no honest image path yet; draw-the-curve stays native).

🤖 Generated with Claude Code

[adamstankiewicz]

Round 2 reconciled against the native registry

The pre-a2learn kinds cut this list both ways, and they yield a design rule: when a proposed primitive overlaps a native kind, design the primitive as that kind's substrate — the thing the kind later reimplements over — never as a parallel cousin. Two implementations of one mechanic drift; a substrate converges. (This is #98's registry-becomes-renderer arc happening one mechanic at a time.)

Where round-2 proposals meet native kinds

Proposal	Native overlap	Disposition
Place	timeline-builder (a time axis is one axis choice)	Build as substrate: axis-generic; timeline-builder later = Place(axis: time) + Response
SpotDifference	find-the-flaw (its core mechanic + assessment)	Build as substrate; find-the-flaw later = SpotDifference + Response + Elaboration
Order	drag-sort (pure duplicate, no generalization win)	Stay unbuilt until the Response tier makes reimplementation worthwhile
Cloze	crossword (same retrieval-with-orthography pedagogy, grid form)	Build Cloze; never primitive-ize the grid
Model	fraction-area-model (the rich continuous case)	Build discrete Model as the composable cousin; native stays for continuous manipulation
Swipe mechanics	swiper-flashcard	Extract as presentation policy — a two-option Check inside a replace-deck can render swipe-style; no new primitive
WhichOne, Tag, Contrast, Notation, Estimate, Anticipate	none	Genuinely new — clear to build

What the native kinds still hold, unmined

• narrated-card → a narrate knob (speech synthesis over any Sequence/Text), not a primitive — decomposes the kind AND gives every composition an accessibility mode for free.
• draw-the-curve → the continuous-sketch commit-then-reveal; Estimate is its scalar shadow. Curve-sketch stays native until a vetted path exists.
• draft-meter / defend-claim → Response(extended-text) + Source + declared rubric — confirms round 1's Source atom and the a2learn interaction contract: a standard event/function vocabulary for registry widgets #99 shape.
• debate-ai / writing-workshop → Dialogue, phase 4 as planned.

Revised build order

1. Pattern library + sample/respace knobs (multiplies existing seven primitives, zero renderer code)
2. Estimate + Anticipate (novel, no native overlap, commitment + generation effects)
3. WhichOne + Tag (novel, no native overlap)
4. Place and SpotDifference — designed substrate-first with their native kinds' future reimplementation as an explicit acceptance test
5. narrate knob (retires narrated-card's uniqueness; accessibility everywhere)

🤖 Generated with Claude Code

[adamstankiewicz]

Round 3 — interactions only agent-generated UI can do

Everything in rounds 1–2 could, in principle, ship in H5P. This round is the moat: mechanics that require a model at interaction time — generating, judging, or improvising in response to what this student just did. Three families.

1. Generative variation (the content is never fixed)

• Remix — an affordance inside the activity: "make this about basketball" (or the student types any interest) → the same composition regenerates with a new surface story, same deep structure. Pedagogy: analogical re-instantiation — varied surface over constant structure is precisely what builds transfer, and no pre-authored system can offer an unbounded re-skin.
• One more, harder — "another one like that" generates a sibling item at nudged difficulty, judged by the agent, not drawn from an item bank. Infinite practice with taste.
• Your work as the material — the student's own attempt (from chat, from a prior Response) becomes the artifact the next activity analyzes: find-the-flaw over your proof, Tag over your paragraph. Error analysis on self-produced artifacts is unauthorable in advance — it's a generation-time pattern, not a primitive.

2. Model-in-the-loop moves (the widget can ask for judgment)

These are #99's payoff — they all ride the a2learn.assist/a2learn.score function channel; the interaction requests, human-written code renders what comes back:

• Grounded hint ladder — "stuck?" produces a hint conditioned on the student's actual state (which pair they keep missing, which wrong option they chose), not a pre-authored hint bank. Escalates Socratically.
• Explain-my-error — after a miss: "why did I think that?" The model names the likely misconception behind that specific wrong choice. Live misconception diagnosis.
• Persona dialogue — interview a red blood cell, cross-examine a primary source's author, debate someone from 1854 — improvised in-character within the activity's frame. debate-ai native is the proof this works; as a primitive it's Dialogue {persona, frame, closure}.
• Protege — teach the confused peer. The model plays a student holding the target misconception; the learner must correct them, and the peer only "gets it" when the explanation is actually sound. The protégé effect / learning-by-teaching (Betty's Brain, Chase et al.) — the strongest uniquely-LLM pedagogy there is, impossible without a model improvising misconception-consistent responses.

3. Natural-language co-construction (words become structure)

• MapBuilder — the student describes relationships ("evaporation connects the ocean to clouds…") and watches a concept map assemble live, then corrects it by talking. NL→validated node/edge data→human-written renderer; concept mapping without drag machinery. Invariant 1 intact: the model emits structure, never markup.
• What-if machine — the student poses any counterfactual inside a bounded domain frame ("what if the denominator were negative?") and the activity answers within its model. Unbounded input, bounded frame — only an LLM handles the input space.

Invariant notes

All model-at-interaction-time calls run server-side under the instance's keys (the score_draft precedent); everything rendered is schema-validated data (a hint is text; a map is nodes/edges). What changes is when generation happens, never who executes. Family 2 and 3 are blocked on #99's function channel by design — and they are the strongest argument for prioritizing it: the moat interactions all need the widget to be able to ask.

🤖 Generated with Claude Code

[adamstankiewicz]

Round 4 — input primitives (sliders, text entry, forms), split by contract

An input in composed UI plays one of three roles, and the roles have different rules. Naming them prevents the classic edtech mistake of one blurry "form field" that quietly becomes surveillance.

1. Inputs as commitment devices — local, build now

The value exists to be committed before a reveal, then self-compared; it never leaves the widget.

• Estimate (round 1): slider commit → reveal actual + gap. The slider exemplar.
• Anticipate (round 1): free-text list → reveal expert list beside it. The text exemplar.
• Generalizes to numeric entry ("write the answer, then see the worked solution"), a date on a range, a point on a scale — all commit → reveal → self-compare, the hypercorrection/generation pattern wearing different input skins. One design system: every commit input renders its reveal as juxtaposition (yours next to actual), never as a verdict badge.

2. Inputs as parameters — local, build now, the gen-UI showpiece

The input configures the content: explanations with knobs.

• Model grows input wiring: a variable can render as a slider/toggle/choice; moving it swaps the outcome content live. "Set the denominator: ▁▂▃ — watch the pieces change."
• Invariant-1 line, drawn hard: the model authors value tables / sampled points, never formulas — a model-authored expression that executes is code running, so the renderer interpolates between authored samples instead. Discrete-and-sampled keeps both honesty (the model must actually know the outcomes it authors) and safety.
• This is also where the basic catalog's unused input components (Slider, ChoicePicker, TextField) finally earn their projection: parameter inputs map onto them almost 1:1.

3. Inputs as collection (forms that submit) — blocked on #99, on purpose

A field whose value leaves the widget is evidence machinery: it needs declared assessmentType, anonymous identity (invariant 2), and the #99 event/function contract. No composed activity gets a quietly-submitting form — the local tier's rule stays: state dies in the component. When #99 lands, collection inputs arrive as Response variants with the submission visible in the schema, never as a side effect of an innocent-looking TextField.

Design rule that falls out

The same rendered control (a slider) is three different primitives depending on where its value goes: nowhere (commit), into the content (parameter), or off the widget (response). The schema should make the destination legible at a glance — which is exactly what a reviewer, a parent, or a district auditor will want to know.

🤖 Generated with Claude Code

[adamstankiewicz]

Round 5 — the free-form tier (Adam's constraint: it should compose its own widgets too)

The alphabet-growth path above has a ceiling: every mechanic is one we named. The free-form tier removes the ceiling without crossing invariant 1, by making behavior itself authorable as data. The ladder of freedom:

1. Closed alphabet (shipped): free structure, fixed vocabulary.
2. Free-form mechanics as data (the target): the composed spec gains a small declarative state layer —
   • state: { varName: { values: [...], initial } } — finite, declared, enumerated;
   • showWhen: { var, equals } on any node — conditional visibility;
   • onTap: [{ set | toggle | cycle }] on tappable nodes — transitions;
   • {var} interpolation in Text.
     With four data-mechanics, the model can design its own widgets: toggles, multi-panel flows, counters, simple state games, choose-your-own mechanics — none of which we pre-named. The human-written interpreter is the only thing that executes.
3. Model-authored code — never. Not sandboxing, not "just this once." The line that makes everything else trustworthy.

Why tier 2 is honest: state is finite and declared, so compositions stay analyzable — the structural gate can check every referenced var exists, every transition targets a declared value, every showWhen is satisfiable, even reachability. Arbitrary code can't be audited; a declared statechart can. "Finite, declared, analyzable" is the free-form honesty line.

Why it's not even proprietary: this is precisely A2UI v1.0's own design — components bind to a dataModel, actions mutate it. Adopting binding/action semantics in the composed alphabet is #98's convergence: our free-form tier and the industry spec are the same shape, so free-form compositions will project to A2UI surfaces almost verbatim.

Relationship to the primitives: the alphabet doesn't become obsolete — named primitives are the quality floor (pedagogically pre-vetted, ergonomic for the model), and free-form is the escape hatch when no primitive fits. Generator guidance: reach for primitives first, compose free-form only when the design genuinely needs a mechanic the alphabet lacks. Evidence rules unchanged: free-form state dies in the component like everything local; assesses derivation simply never finds a verdict-carrier in a statechart.

Sequencing: after Response (#99) rather than before — measured interactions unlock more value than unnamed mechanics, and the state layer's schema deserves a design pass against A2UI's dataModel spelling so the projection stays 1:1.

🤖 Generated with Claude Code