Smart Learning Algorithm

Overview

Civix uses a professional SM-2 Spaced Repetition algorithm (the same algorithm used by Anki) to optimize learning and ensure users achieve high-retention mastery before their citizenship test.

Current implementation includes additional hardening for USCIS exemption paths:

• Senior mode stays strictly within the 65/20 question set.
• State-dependent senior questions are only prioritized when they are evaluatable from profile context.
• Store-level fallbacks preserve senior scope instead of silently returning standard pool questions.

---

Core Algorithm: SM-2 Spaced Repetition

How It Works

1. Quality Rating (0-5 scale)

   • Calculated based on: correctness, response time, streak
   • Wrong answer: 0-2
   • Correct but slow: 3
   • Correct and quick: 4-5

2. Ease Factor (EF)

   • Starts at 2.5 for new questions
   • Adjusts based on performance: EF' = EF + (0.1 - (5-q) * (0.08 + (5-q) * 0.02))
   • Minimum: 1.3 (harder questions need more review)

3. Interval Calculation

   • First review: 1 day
   • Second review: 6 days
   • Subsequent: interval * EF
   • Failed questions reset to 1 day

Mastery Criteria

A question is considered mastered when:

• Streak >= 3 (correct 3 times in a row)
• Seen >= 5 times total
• Accuracy >= 80% (correct/total)

Test Ready Status

User is Test Ready when:

• 90% or more questions are mastered
• No critical weak topics remain

---

File Locations

File	Purpose
/lib/algorithm.ts	Core SM-2 algorithm implementation
/store/useAppStore.ts	State management integration
/app/(tabs)/results/completion.tsx	Mastery visualization

---

Key Functions

/lib/algorithm.ts

// Calculate new stats after answering
updateQuestionStats(currentStats, correct, timeSpentMs, avgTimeMs)

// Select questions intelligently
selectQuestions(pool, count, stats, weakTopics, mode, options)

// Exam simulation (20 questions standard / 10 for 65/20, like real USCIS 2025 test)
selectExamQuestions(pool, stats, isSenior)

// Get overall mastery progress
calculateMasteryProgress(pool, stats)

// Get progress by category
calculateCategoryProgress(pool, stats)

// Identify weak topics
getWeakTopics(pool, stats, limit)

// Generate personalized recommendations
getStudyRecommendations(progress, categoryProgress, dueCount, { isSeniorMode })

Store Integration

// New state properties
questionStatsV2: Record<string, AlgoQuestionStats>
isSeniorMode: boolean

// New actions
startSmartPractice(mode, options)
startExamSimulation()
answerWithAlgorithm(questionId, correct, timeSpentMs)

// New getters
getMasteryProgress()
getCategoryProgress()
getWeakTopicsAnalysis()
getRecommendations()
isTestReady()

---

Study Modes

Mode	Description
learn	Prioritize new questions
review	Focus on due questions
exam	Simulate real test (20 questions, 12 to pass; or 10 for 65/20)
weak	Target weak topics
coverage	Ensure all questions seen
senior	65+ mode (20 designated questions, 10 asked, 6 to pass); evaluatable-first when state profile is missing

---

Question Selection Priority

Questions are scored based on:

1. Overdue Bonus (+100 for overdue questions)
2. Due Bonus (+50 for questions due today)
3. Weak Topic Bonus (+30 for weak category questions)
4. New Question Bonus (+25 for unseen questions)
5. Ease Factor Penalty (lower EF = higher priority)
6. Recently Seen Penalty (-20 for questions seen in last 4 hours)

---

USCIS Test Format (2025)

• Standard Test: 128-question pool; 20 asked, must get 12 correct to pass
• 65+ Senior Test: 20 designated questions (marked in bank); 10 asked, must get 6 correct

The question bank (lib/bank/en.ts) and algorithm use the same IDs (q1–q128) and correct answers; selection and pass/fail rules match official USCIS 2025 (M-1778). The algorithm ensures comprehensive coverage of:

• American Government
• American History
• Integrated Civics

---

Completion Page Features

The smart completion page shows:

1. Dual Progress Display

   • Session score (this session)
   • Overall mastery (lifetime)

2. Journey to 100%

   • Progress bar toward 90% mastery (Test Ready)
   • Visual milestone at 90%

3. Smart Insights Grid

   • Mastered count (green)
   • Learning count (yellow)
   • Due for review (orange)
   • New questions (blue)

4. Weak Categories

   • Top 3 categories needing work
   • Visual progress bars per category

5. Personalized Recommendations

   • Algorithm-generated tips
   • Based on actual user data and senior/standard mode context

6. Smart Next Action

   • Context-aware suggested action
   • Routes to most beneficial activity

---

Best Practices

1. Daily Practice - Consistency beats cramming
2. Review Due Questions - Don't let them become overdue
3. Focus on Weak Topics - Address gaps systematically
4. Use Exam Mode - Simulate real test conditions
5. Trust the Algorithm - It optimizes your learning path

---

Future Enhancements

• OpenAI integration for personalized coaching
• Voice-based practice (like real interview)
• Adaptive difficulty adjustment
• Social/competitive features

Recent Optimization Notes

• weightedShuffle now pre-normalizes weight totals once before selection.
• Senior mode selection avoids non-evaluatable state-dependent items when context is absent.
• Home/interview screens now use Zustand selectors (useShallow where needed) to reduce unnecessary re-renders.