๐Ÿ›๏ธ

Civics by Forgeboro • Documentation Manual

U.S. Citizenship Exam Prep • SM-2 Spaced Repetition • Active Recall

๐Ÿš€ Quick Start & Application Overview

Civics by Forgeboro is an intelligent exam preparation and active-recall practice platform designed for citizenship test applicants, high school students, and civics enthusiasts. It combines official USCIS question datasets updated with the current list of elected officials across all circumscriptions of the USA with algorithmic spaced repetition.

The 10-Second Rule: All featuresโ€”drills, audio playback, representative lookups, and score logsโ€”run entirely client-side without registration barriers.

How to Practice

  • Select Deck: Choose between Comprehensive Civics Decks, Short Drill Batches, or Historical subsets.
  • Formulate Your Response: Read or listen to the question, type your thoughts or recite mentally.
  • Reveal & Self-Assess: Click Reveal Answer and grade yourself honestly.

๐Ÿง  Active Recall & Self-Assessment Workflow

Passive memorization (simply reading question-and-answer pairs) yields low long-term retention. Civics uses Active Retrieval Practice:

  • Question Presentation: Only the question prompt is initially displayed, encouraging neural activation.
  • Answer Reveal: Revealing displays official USCIS test answers and acceptable alternatives.
  • Self-Assessment Feedback: Selecting I Got It advances the review interval, while Needs Practice schedules the question for imminent re-test.

๐Ÿ“ˆ SuperMemo-2 (SM-2) Spaced Repetition

Civics mathematically schedules question review intervals based on a refined implementation of the SuperMemo-2 (SM-2) spaced repetition algorithm:

  • Ease Factor Clamping: Dynamic ease factor starts at 2.5 and is strictly clamped to a floor of 1.3 to avoid interval stagnation.
  • Interval Progression: Correct responses advance intervals from 1 day to 6 days, then exponentially multiply by ease factor.
  • Memory Lapses: Any incorrect self-assessment resets the item's repetition level to 0 and interval to 1 day for prompt reinforcement.

๐ŸŒฑ Botanical Mastery Stages

Progress across the question deck is visualized in the Growth & Mastery progress bar:

  • ๐ŸŒฑ Unplanted (< 4 days): New questions or items that experienced a memory lapse.
  • ๐ŸŒฟ Seeded (4โ€“9 days): Questions successfully recalled once or twice; early consolidation.
  • ๐ŸŒฒ Sprouting (10โ€“29 days): Solid intermediate retention requiring periodic maintenance.
  • ๐ŸŒณ Deep Rooted (โ‰ฅ 30 days): Long-term conceptual mastery solidified in permanent memory.

๐Ÿ“ State & Representative Localization

Certain USCIS citizenship test questions vary depending on where you reside (e.g., Who is one of your state's U.S. Senators now? or Name your U.S. Representative).

Civics automatically synchronizes with federal datasets based on your chosen state and congressional district, dynamically populating question variables (such as ${senator}, ${governor}, ${representative}) with verified current officials.

๐Ÿ”Š Voice Audio Pronunciation

Every question features natural voice pronunciation to assist English learners and auditory study sessions. Click the Listen button or press Space to hear the prompt read aloud.

๐Ÿ’พ Cryptographic State Transfer & Backup

Civics stores all quiz history, spaced repetition intervals, and daily habit streak counters locally in browser storage. To safeguard your progress across devices:

  • Export Backup: Generates a signed, canonical JSON file with an HMAC-SHA256 signature preventing data corruption.
  • Restore Backup: Uploads your backup file, verifies cryptographic integrity, and restores your deck progress.
  • Chunking Support: Datasets exceeding 3.5 MB are automatically sliced and reassembled without data loss.

โŒจ๏ธ Keyboard Shortcuts

  • Enter — Reveal official USCIS answer / advance to next card
  • Space — Play audio pronunciation
  • 1 — Self-grade: Needs Practice
  • 2 — Self-grade: I Got It!

๐Ÿค– AI Agent Automation Protocol

Civics exposes a machine-readable automation specification via window.__CIVICS_AGENT_SPEC__ and at /agent-spec.json. AI coding agents and headless evaluation tools can automate testing workflows via standardized DOM hooks:

  • [data-tool="quiz-session"] — Main quiz card workspace
  • [data-action="reveal-answer"] — Button revealing answer text
  • [data-action="score-correct"] — Self-assessment button for successful recall
  • [data-action="export-backup"] — Trigger for state backup downloads