Developer Guide

Interventions: Adaptive Error Correction

When a student answers incorrectly, the Fluency API analyzes their error pattern and recommends a specific intervention type. You implement the UI; the API provides the intelligence.

Why Interventions Matter

Research shows that immediate, targeted error correction is one of the most powerful tools for building durable memory. Without intervention, students may encode incorrect associations (like "7 × 8 = 54") into long-term memory, creating persistent errors that are hard to unlearn.

Key learning science principles:

  • Immediate feedback prevents incorrect answers from being stored in memory
  • Active recall (reproducing the answer) builds stronger memory traces than passive review
  • Varied practice modalities (visual, audio, kinesthetic) engage multiple memory pathways
  • Escalating support adapts to error patterns—simple mistakes get quick corrections, persistent errors get deeper remediation

The intervention system implements these principles automatically. The API detects error patterns and selects the appropriate intervention type. You implement the UI for each type.

How the API Selects Interventions

The API uses error history and answer patterns to determine which intervention to apply:

  1. Reuse previous intervention: If the question already has an intervention in its history, reuse that same type.
  2. Near-neighbor error (multiplication/division): If the student's answer matches a nearby fact (e.g., 7×8 vs 7×9), use NearNeighborContrast with ordered distractors.
  3. Off-by-one/two error (addition/subtraction): Use NumberLineHop to visualize the correct hop sequence.
  4. Cross-operation confusion (e.g., answering 7+8 when asked 7×8): Use TurnWheels.All.
  5. Repeated error in session: Select a Production/High-Effort tool at random.
  6. First error: Select a Scaffolded/Low-Effort tool at random.

Current tool pools:

  • Scaffolded / Low-Effort: CueFading.FRQ, TurnWheels.AnswerOnly, Retry.MCQ, DragDrop.AnswerOnly
  • Production / High-Effort: DragDrop.FITB, CueFading.ListenMCQFRQ, TimedRepetition.Recall.FRQ, AnswerFirst.MCQ.FRQ
  • Targeted Error-Pattern: NearNeighborContrast, NumberLineHop
  • Specialist: TurnWheels.All

The selection algorithm adapts based on the student's current session performance, their historical accuracy with this fact, and the type of error made. You don't control which intervention is selected—the API provides this intelligence.

Intervention Types Reference

Each intervention type serves a specific pedagogical purpose. The API returns an interventionType string; you implement the corresponding UI flow.

Note: TrashCat's game shows one way to implement these interventions. Your implementation can differ—use your app's visual style, interaction patterns, and technical constraints. The core learning mechanics should remain consistent, but the presentation is yours to design.

None

What it is: No intervention needed. Student continues to the next question.

When triggered: First-time correct answer, or after a failed intervention when the system decides to move forward.

Implementation: No special UI. Simply proceed to the next question.

AnswerFirst.MCQ.FRQ

What it is: Reverse-equation recognition followed by free response.

When triggered: Student's first or second error on this fact during the current session.

Reference Video: ▶️ Watch AnswerFirst.MCQ.FRQ

Steps:

  1. MCQ (fact choices, not timed): Show a reverse equation and a list of fact choices (e.g., ? × ? = 56). Audio auto-plays. Input: select a fact. Wrong answers repeat this step.
  2. Keypad (not timed): Show the original equation and a keypad (e.g., 7 × 8 = ?). Input: numeric entry. Wrong answers return to the MCQ step.

CueFading.FRQ

What it is: Progressive cue fading: click the full answer, then recall with a partial cue, then recall with no cue.

When triggered: First error on a fact the student has seen before (not brand new).

Reference Video: ▶️ Watch CueFading.FRQ

Steps:

  1. Click Answer (not timed): Show the equation with the full answer as a clickable button (e.g., 7 × 8 = 56). Audio auto-plays. Input: click the answer to continue.
  2. Keypad (missing digit, not timed, multi-digit only): Show a single missing digit prompt (e.g., 7 × 8 = 5_). Input: enter the missing digit. Wrong answers return to the Click Answer step.
  3. Keypad (full answer, not timed): Show the equation with a blank answer (e.g., 7 × 8 = ?). Input: type the full answer. Wrong answers return to the previous step (missing-digit if shown, otherwise Click Answer).

CueFading.ListenMCQFRQ

What it is: Multi-modal reinforcement: audio playback, then MCQ, then free response.

When triggered: Second error on a fact, particularly when audio reinforcement may help.

Reference Video: ▶️ Watch CueFading.ListenMCQFRQ

Steps:

  1. Audio Button (not timed): Show the equation with a “listen” button (e.g., 7 × 8 = ?). Input: tap to play audio.
  2. MCQ (not timed): Show the equation and multiple-choice answers (e.g., 7 × 8 = ?). Audio auto-plays. Input: select a choice. Wrong answers return to the Audio Button step.
  3. Keypad (not timed): Show the equation with a keypad (e.g., 7 × 8 = ?). Input: numeric entry. Wrong answers return to the MCQ step.

Audio can be generated using text-to-speech or pre-recorded. The key is multi-sensory encoding (auditory + visual + recall).

DragDrop.AnswerOnly

What it is: Drag-and-drop answer selection using full answer tiles.

When triggered: Second or third error when kinesthetic interaction may strengthen memory.

Reference Video: ▶️ Watch DragDrop.AnswerOnly

Steps:

  1. Display (not timed): Show the full equation with the correct answer visible as a cue (e.g., 7 × 8 = 56). Audio auto-plays and the step waits for audio to finish.
  2. Drag-and-Drop Answer (not timed): Show the equation with an answer slot and draggable answer tiles (e.g., 7 × 8 = __ with tiles like 56, 54, 64). Input: drag the full answer tile into the slot. Wrong placements reset back to the Display step.

For multi-digit answers, students must place each digit in the correct position. The physical act of "building" the answer reinforces memory through motor interaction.

DragDrop.FITB

What it is: Drag-and-drop fill-in-the-blank for the entire equation (both factors and the answer) using full-value tiles.

When triggered: Second or third error when full equation reconstruction helps reinforce the relationship.

Reference Video: ▶️ Watch DragDrop.FITB

Steps:

  1. Display (not timed): Show the full equation with the correct answer visible as a cue (e.g., 7 × 8 = 56). Audio auto-plays and the step waits for audio to finish.
  2. Drag-and-Drop Full Equation (not timed): Show blank slots for both factors and the answer with draggable tiles (e.g., __ × __ = __ with tiles like 7, 8, 56, plus distractors). Input: drag full-value tiles into all slots. Commutative property applies only when swapping factors preserves the result. Wrong placements reset back to the Display step.

This differs from DragDrop.AnswerOnly—here the student must reconstruct the entire equation, not just the answer, and factor order only applies when commutative.

NearNeighborContrast

What it is: Timed contrast display plus MCQ to separate visually similar facts.

When triggered: Student's incorrect answer matches the result of a nearby multiplication/division fact.

Reference Video: ▶️ Watch NearNeighborContrast

Steps:

  1. Contrast Display (timed): Show the correct equation alongside a near-neighbor distractor card (e.g., 7 × 8 = 56 next to 7 × 9 = 63). Audio auto-plays. No input.
  2. MCQ (not timed): Show the standard MCQ choices for the question (e.g., 7 × 8 = ?). Input: select a choice. Wrong answers return to the Contrast Display step.

This intervention targets visual/structural confusion between adjacent facts by forcing deliberate comparison.

NumberLineHop

What it is: Timed number-line hop animation followed by a timed check.

When triggered: Student is off by 1 or 2 on addition/subtraction (and the second operand is non-zero).

Reference Video: ▶️ Watch NumberLineHop

Steps:

  1. Display (not timed): Show the full equation with the correct answer visible as a cue (e.g., 6 + 4 = 10). Audio auto-plays and the step waits for audio to finish.
  2. Number Line Hop (timed): Animate the hop sequence to the correct endpoint (e.g., hop 4 steps from 6 to 10). No input.
  3. MCQ (timed): Re-ask the question with multiple-choice answers (e.g., 6 + 4 = ?). Input: select a choice. Wrong or timed-out answers return to the Number Line Hop step.

This intervention corrects small counting errors by reinforcing the step-by-step hop logic.

Retry.MCQ

What it is: Brief cue of the correct equation, then immediate re-ask via MCQ.

When triggered: First error when the mistake appears to be a mis-click or attention lapse (not conceptual confusion).

Reference Video: ▶️ Watch Retry.MCQ

Steps:

  1. Display (not timed): Show the full equation with the correct answer visible as a cue (e.g., 7 × 8 = 56). Audio auto-plays and the step waits for audio to finish.
  2. MCQ (not timed): Re-ask the same question with the same choices (e.g., 7 × 8 = ?). Input: select a choice. Wrong answers return to the Display step.

This is the lightest intervention—simply giving the student another chance without additional scaffolding.

TimedRepetition.Recall.FRQ

What it is: Timed copy-cover-recall: show the full equation, then a timed recall input.

When triggered: Third or more consecutive errors—indicates need for extended, deliberate practice.

Reference Video: ▶️ Watch TimedRepetition.Recall.FRQ

Steps:

  1. Display (timed): Show the full equation with the correct answer visible (e.g., 7 × 8 = 56). Audio auto-plays. No input.
  2. Keypad (timed): Show the equation with a keypad (e.g., 7 × 8 = ?). Input: numeric entry. Wrong or timed-out answers return to the Display step.

This intervention is more time-intensive but builds stronger memory through deliberate, effortful recall.

TurnWheels.All

What it is: Scrollable digit wheels for the entire equation (factors and answer).

When triggered: Second or third error when interactive manipulation may help.

Reference Video: ▶️ Watch TurnWheels.All

Steps:

  1. Display (not timed): Show the full equation with the correct answer visible as a cue (e.g., 7 × 8 = 56). Audio auto-plays and the step waits for audio to finish.
  2. Scroll Wheels (not timed): Show wheels for both factors and the answer (e.g., ? × ? = ?). Input: scroll digits until the full equation is correct (supports commutative property). Completes on correct entry; no timeout.

This combines visual and kinesthetic learning—students physically manipulate all parts of the equation.

TurnWheels.AnswerOnly

What it is: Scrollable digit wheels for the answer only (equation is shown).

When triggered: Similar to TurnWheels.All but with reduced context.

Reference Video: ▶️ Watch TurnWheels.AnswerOnly

Steps:

  1. Display (not timed): Show the full equation with the correct answer visible as a cue (e.g., 7 × 8 = 56). Audio auto-plays and the step waits for audio to finish.
  2. Scroll Wheels (not timed): Show wheels for the answer only (e.g., 7 × 8 = ?). Input: scroll digits until the answer is correct. Completes on correct entry; no timeout.

Implementation Strategies

MVP Approach: Skip Interventions

For your first integration, disable interventions entirely:

capabilities: {
  intervention: false;
}

The API will never return intervention types. Show simple correct/incorrect feedback and move to the next question. This lets you validate the core learning loop before adding intervention complexity.

To force a specific intervention during testing:

capabilities: {
  intervention: true;
  interventionTypeOverride: 'CueFading.FRQ';
}

Progressive Approach: Implement Subset

Implement interventions in phases based on complexity:

Phase 1: Simple interventions (minimal UI work)

  • None (default)
  • Retry.MCQ (reshow question)
  • CueFading.FRQ (flash answer, test recall)

Phase 2: Interactive interventions (moderate UI work)

  • DragDrop.AnswerOnly
  • DragDrop.FITB

Phase 3: Advanced interventions (significant UI work)

  • AnswerFirst.MCQ.FRQ
  • CueFading.ListenMCQFRQ
  • TimedRepetition.Recall.FRQ
  • TurnWheels.All
  • TurnWheels.AnswerOnly
  • NearNeighborContrast
  • NumberLineHop

For unimplemented types, fall back to a simpler intervention (e.g., treat TurnWheels.All as CueFading.FRQ).

Full Approach: All Intervention Types

Implement all intervention types to provide the complete adaptive learning experience. This gives the API maximum flexibility to select the optimal remediation strategy for each student's error pattern.

Reference Implementation

TrashCat's Unity game provides a complete reference implementation of all intervention types. You can review the code, see the UI patterns, and watch the embedded videos above to understand how each intervention works in practice.

Important: Your implementation doesn't need to match TrashCat's visual design. The core learning mechanics (what information is shown, how long it's visible, what the student must do) should remain consistent, but adapt the presentation to your app's style, technical platform, and user experience.

Access the reference implementation:

Related Docs

Getting Started

Authentication and basic learning loop. Start here if you haven't integrated the API yet.

Complete Example

Production code showing how to integrate interventions into a full learning session with error handling and state management.

API Reference

Complete documentation of the answer submission endpoint, including all capabilities options and feedback response structure.

Previous
Timing Fields
Next
Leaderboards