Spaced review

Spaced Review -- Retention Testing

If you can't explain a concept from memory, you don't know it. This skill ensures knowledge sticks.

Trigger

• /review-deck or "quiz me"
• At session start when cards are due for review
• After exercises (to add new concepts)

Data File

reflections/spaced-review-deck.json

Card Schema

{
  "concept": "async/await",
  "category": "python",
  "topic": 1,
  "date_learned": "2026-04-08",
  "last_reviewed": "2026-04-11",
  "next_review": "2026-04-15",
  "interval_days": 4,
  "ease_factor": 2.5,
  "repetitions": 2,
  "quality_history": [4, 3]
}

FSRS-Inspired Scheduling

After each review, the student rates recall quality 0-5:

• 5 -- Perfect: Instant, deep, with production context. → interval *= ease; ease += 0.1
• 4 -- Good: Correct and understood, minor hesitation. → interval *= ease
• 3 -- Acceptable: Correct but shallow, needed a moment. → interval *= ease; ease -= 0.05
• 2 -- Struggled: Got there with hints. → interval = 1; ease -= 0.15
• 1 -- Failed: Couldn't explain. → interval = 1; ease -= 0.2
• 0 -- Blank: No recall at all. → interval = 1; ease = max(1.3, ease - 0.3)

Initial intervals: Day 1 → 1 day. Day 2 → 3 days. Then algorithm takes over. Minimum ease factor: 1.3 (prevents intervals from collapsing permanently).

Execution

Adding Concepts (after exercises)

1. After the student completes an exercise, identify key concepts
2. Ask: "What concepts from today should go in your review deck?"
3. The student names them. Create cards with interval = 1 day.
4. Also flag concepts they struggled with during the exercise.

Reviewing (at session start or on demand)

1. Read deck, find cards where next_review <= today
2. For each due card:
   • Ask the student to explain the concept from memory. No looking up code.
   • Ask a depth question: "What happens when this fails?" or "How does this work under the hood?"
   • Ask a production question: "How would this behave at 10x scale?"
3. The student rates quality (0-5). Update card scheduling.
4. Write updated deck back to JSON.

Analytics (on demand)

REVIEW DECK -- {date}
Total concepts: X
Due today: X
Mastered (5+ streak at quality 4+): X
Struggling (ease < 1.8): X
Categories: python: X, rag: X, agents: X, ...

Rules

• NEVER give the answer. If the student fails, say "review tonight" and move on.
• Questions test understanding, not memorization ("explain why" not "what is").
• Connect recall to production: use the student's domain from memory/user_domain.md for examples.
• If multiple cards in a category are struggling → flag the topic for revisiting.
• Cross-reference with /assess results for comprehensive gap analysis.

Session-Start Retention Gate

At the start of every session (after the system integrity gate but before topic work):

1. Read reflections/spaced-review-deck.json.
2. If any cards are due (next_review <= today), BLOCK progression.
3. The student must complete the due cards before starting new work.
4. Cards rated 0-2 (failed or struggled) are re-queued for the next session AND trigger a "concept at risk" note.
5. If a card has been rated 0-2 three times in a row, the underlying exercise is flagged for re-study — the student goes BACK to that exercise.

Why this gate exists: Without enforcement, students skip review. Without review, knowledge fades. Without fresh knowledge, later topics become impossible. The gate is painful on day one but saves weeks of confusion later.

Override: The student can say "skip review, I'll do it after the session" — but that must be recorded in PROGRESS.md so the pattern is visible. Repeated skipping is a red flag.