# Scheduler Tuning History

This document tracks adjustments to the spaced repetition algorithm parameters.

---

## Current Settings (Phase 1)

| Box | Selection Rule | Rationale |
|-----|----------------|-----------|
| Box 0 | ALL cards | Need the most work |
| Box 1 | 50% of cards | Still learning |
| Box 2 | 1 card max | Already got twice, light refresh |
| Box 3 | 1 card only when 8+ in Box 3 | Pre-graduation confirmation only |

**Graduation:** 10 cards in Box 3 → retire batch, add 10 new cards

---

## Change Log

### 2026-04-15: Cram mode (3-day deadline)

**Problem:** Need to learn the entire list in 3 days. Mastery needs to come sooner per batch and review of already-known cards is wasted time.

**Changes:**
- `FOCUS_SET_SIZE` 12 → 8 (smaller batches → more reps/card/session → faster box climbs)
- `STABLE_CORRECT_COUNT` 3 → 2 (promote between boxes after 2 correct instead of 3)
- `GRADUATION_THRESHOLD` 10 → 6 (75% of focus set, similar quality bar to old 83%)
- `GRADUATION_KEEP_SHAKY` 2 → 1
- `PHASE_2_SESSION_SIZE` 20 → 5 (deprioritize non-focus review)
- Phase 1 Box 2: dropped from sessions entirely
- Phase 1 Box 3 gate: 8 → 5 (scaled to new graduation threshold)
- Phase 2: restricted to Box 1–2 only (Box 3–5 deferred until after deadline)

**Rationale:** Optimize for throughput on the 150-card list within 3 days. Long-term retention (4+ days out) will suffer; revert after the deadline.

**Revert target:** restore values from the Phase 1 table above and re-enable Box 2 in `buildPhase1Session`, all-box Phase 2 query.

**Files changed:** `constants.ts`, `session-builder.ts`

---

### 2025-04-10: Reduce Box 2-3 frequency

**Problem:** Users reported seeing too many already-mastered problems. Box 2-3 cards appeared every session even though they were well-learned.

**Changes:**
- Box 2: Reduced from 1-2 cards → 1 card max
- Box 3: Changed from "1 card every session" → "1 card only when 8+ cards in Box 3"

**Rationale:** Box 3 cards only need a final confirmation right before graduation. Showing them every session wastes time and feels repetitive. The 8+ threshold means they only appear when graduation is imminent.

**Files changed:** `session-builder.ts` (`buildPhase1Session`)

---

## Parameters Reference

See `constants.ts` for all tunable values:

```
FOCUS_SET_SIZE = 12          # Cards in active rotation
GRADUATION_THRESHOLD = 10    # Cards needed in Box 3 to graduate
GRADUATION_KEEP_SHAKY = 2    # Shaky cards kept after graduation
PHASE_1_TOTAL_PROBLEMS = 150 # Problems before Phase 2 transition
RETRY_DELAY_PROBLEMS = 3     # Wait N problems before retry
```

---

## Ideas for Future Tuning

- [ ] Add time-based spacing within Phase 1 (don't show Box 2+ if correct in last N minutes)
- [ ] Graduate cards individually instead of in batches
- [ ] Adjust Box 1 percentage based on session length
- [ ] Track per-user accuracy and adjust dynamically