|
1
|
--- |
|
2
|
name: flashcard-generator |
|
3
|
description: Generate flashcards, quizzes, and study guides from notes or topics. |
|
4
|
--- |
|
5
|
|
|
6
|
# Flashcard & Quiz Generator |
|
7
|
|
|
8
|
Generate study materials grounded in memory science. Follow Wozniak's formulation rules, schedule with SM-2, export to Anki via `genanki`. |
|
9
|
|
|
10
|
## When to Use |
|
11
|
|
|
12
|
- User pastes notes/textbook content to convert to cards, needs exam prep, or wants an Anki deck |
|
13
|
|
|
14
|
## When NOT to Use |
|
15
|
|
|
16
|
- In-depth research (deep-research), data analysis (data-analysis) |
|
17
|
|
|
18
|
## Why Spaced Repetition Works |
|
19
|
|
|
20
|
Ebbinghaus (1885) showed memory decays as `R = e^(-t/S)`where`S`is memory stability — without review, ~50-70% of new information is gone within 24 hours. The curve was replicated in 2015 (Murre & Dros, PLOS ONE). Each successful recall increases`S`, flattening the curve. **The core insight: reviewing just before you'd forget is the most efficient moment to review.** Active recall (retrieving the answer) builds stability far more than passive re-reading — this is why cards beat highlighting. |
|
21
|
|
|
22
|
## Card Formulation: Wozniak's 20 Rules |
|
23
|
|
|
24
|
Piotr Wozniak (SuperMemo creator; Anki forked his SM-2 algorithm) published the canonical rules in 1999 at supermemo.com. The ones that matter most for card generation: |
|
25
|
|
|
26
|
**Rule 1-2: Understand before you memorize.** Don't make cards for material the user hasn't grasped yet. Cards reinforce; they don't teach. |
|
27
|
|
|
28
|
**Rule 4: Minimum Information Principle — the single most important rule.** One atomic fact per card. Complex cards get forgotten as a unit — if any part fails, the whole card resets. Split aggressively. |
|
29
|
|
|
30
|
- Bad: `Q: What are the three branches of US government and what does each do?` (6 facts, fails together) |
|
31
|
- Good: Six cards. `Q: Which branch of US government writes laws? A: Legislative` × each branch × each function. |
|
32
|
|
|
33
|
**Rule 5: Cloze deletion is the fastest path from prose to cards.** Take a sentence, blank one term. Beginners who struggle with minimum-information should default to cloze. |
|
34
|
|
|
35
|
- Source: `TCP guarantees ordered delivery; UDP does not.` |
|
36
|
- Cards: `{{c1::TCP}} guarantees ordered delivery; {{c2::UDP}} does not.` → 2 cards from one sentence |
|
37
|
|
|
38
|
**Rule 9-10: Avoid sets and enumerations.**"List all 7 OSI layers" is a nightmare card — high failure rate, painful reviews. Instead, use**overlapping cloze**: one sentence with the full list, generate N cards each blanking one item. The redundancy is intentional — it's extra *cards*, not extra info per card. |
|
39
|
|
|
40
|
**Rule 11: Combat interference.** Similar cards confuse each other (`affect`vs`effect`, port 80 vs 443). Add disambiguating context:`Q: [web, unencrypted] Default HTTP port? A: 80`. |
|
41
|
|
|
42
|
**Rule 14: Personalize.** `Q: What's O(n log n)? A: Merge sort — like the algorithm you botched in the Stripe interview` sticks better than the abstract definition. |
|
43
|
|
|
44
|
**The diagnostic:** If a card's ease factor drops below 1.3 in review, the card is malformed, not hard. Rewrite it, don't grind it. |
|
45
|
|
|
46
|
## Card Types |
|
47
|
|
|
48
|
| Type | Use for | Example | |
|
49
|
|
|
50
|
|---|---|---| |
|
51
|
|
|
52
|
| **Basic Q→A** | Single facts | `Q: Capital of Mongolia? A: Ulaanbaatar` | |
|
53
|
|
|
54
|
| **Cloze** | Converting prose fast; lists | `The {{c1::mitochondria}} produces {{c2::ATP}} via {{c3::oxidative phosphorylation}}` → 3 cards | |
|
55
|
|
|
56
|
| **Reversed** | Bidirectional recall (vocab) | Generates both `fr→en`and`en→fr` | |
|
57
|
|
|
58
|
| **Application** | Understanding, not recall | `Q: Revenue +20%, profit −5%. Why? A: Costs grew faster than revenue` | |
|
59
|
|
|
60
|
| **Image occlusion** | Anatomy, diagrams, maps | Blank one label on a diagram per card (Wozniak rule 8) | |
|
61
|
|
|
62
|
Mix Bloom's levels: ~40% remember (basic/cloze), ~30% understand, ~30% apply/analyze. Pure recall decks feel productive but fail on exams that test transfer. |
|
63
|
|
|
64
|
## SM-2 Scheduling (What Anki Runs) |
|
65
|
|
|
66
|
Wozniak's 1987 algorithm. Each card tracks three values: repetition count `n`, ease factor`EF`(starts at 2.5), interval`I` in days. After each review, grade 0-5: |
|
67
|
|
|
68
|
```text |
|
69
|
|
|
70
|
if grade >= 3: \# correct |
|
71
|
|
|
72
|
if n == 0: I = 1 |
|
73
|
|
|
74
|
elif n == 1: I = 6 |
|
75
|
|
|
76
|
else: I = round(I * EF) \# exponential growth |
|
77
|
|
|
78
|
n += 1 |
|
79
|
|
|
80
|
else: \# forgot |
|
81
|
|
|
82
|
n = 0; I = 1 \# reset interval, keep EF |
|
83
|
|
|
84
|
EF += 0.1 - (5-grade) * (0.08 + (5-grade)*0.02) |
|
85
|
|
|
86
|
EF = max(EF, 1.3) \# floor — below this, card is malformed |
|
87
|
|
|
88
|
``` |
|
89
|
|
|
90
|
Grade 5 → EF +0.10. Grade 4 → no change. Grade 3 → EF −0.14. A card you always rate "good" (4) with EF 2.5 goes: 1 → 6 → 15 → 38 → 94 days. **FSRS** (Anki 23.10+) is the ML successor — fits a personal forgetting curve, ~20-30% fewer reviews for same retention. Mention it; default to SM-2 for simplicity. |
|
91
|
|
|
92
|
## Export to Anki: `genanki` |
|
93
|
|
|
94
|
`pip install genanki`(github.com/kerrickstaley/genanki). Generates`.apkg` files that import directly via File → Import. |
|
95
|
|
|
96
|
```python |
|
97
|
|
|
98
|
import genanki, random |
|
99
|
|
|
100
|
# Generate these ONCE, then hardcode — stable IDs let users re-import updates |
|
101
|
|
|
102
|
MODEL_ID = random.randrange(1 << 30, 1 << 31) \# e.g. 1607392319 |
|
103
|
|
|
104
|
DECK_ID = random.randrange(1 << 30, 1 << 31) |
|
105
|
|
|
106
|
basic = genanki.Model(MODEL_ID, 'Basic', |
|
107
|
|
|
108
|
fields=[{'name': 'Q'}, {'name': 'A'}], |
|
109
|
|
|
110
|
templates=[{'name': 'Card 1', 'qfmt': '{{Q}}', |
|
111
|
|
|
112
|
'afmt': '{{FrontSide}}<hr id="answer">{{A}}'}], |
|
113
|
|
|
114
|
css='.card { font-family: Arial; font-size: 20px; text-align: center; }') |
|
115
|
|
|
116
|
deck = genanki.Deck(DECK_ID, 'Biology :: Cell Structure') |
|
117
|
|
|
118
|
deck.add_note(genanki.Note(model=basic, |
|
119
|
|
|
120
|
fields=['What organelle produces ATP?', 'Mitochondria'])) |
|
121
|
|
|
122
|
# Cloze uses built-in model — second field required (can be empty) since 0.13.0 |
|
123
|
|
|
124
|
deck.add_note(genanki.Note(model=genanki.builtin_models.CLOZE_MODEL, |
|
125
|
|
|
126
|
fields=['The {{c1::mitochondria}} produces {{c2::ATP}}', ''])) |
|
127
|
|
|
128
|
genanki.Package(deck).write_to_file('cells.apkg') |
|
129
|
|
|
130
|
``` |
|
131
|
|
|
132
|
**Gotchas:** Fields are HTML — `html.escape()`any user content with`<`,`>`,`&`. For images/audio, set`package.media_files = ['diagram.png']`and reference by **basename only** in the field:`<img src="diagram.png">`(paths break). Stable GUIDs let re-imports update cards in place — subclass`Note`and override`guid` to hash only the question field. |
|
133
|
|
|
134
|
**Quizlet/CSV fallback:** Tab-separated, one card per line: `question\tanswer\n`. Quizlet imports directly. Also works for Anki's File → Import → Text. |
|
135
|
|
|
136
|
## Output: Always Build a Web App |
|
137
|
|
|
138
|
**Every flashcard generation MUST produce an interactive web app as the primary output.**Do not output cards as plain text or markdown — always build a React + Vite single-page app with**two modes** the user can switch between: |
|
139
|
|
|
140
|
### Mode 1: Flashcard Review |
|
141
|
|
|
142
|
1. **Card display** — show front of card, flip to back on click or spacebar |
|
143
|
2. **SM-2 grading**— four buttons: Again (1), Hard (3), Good (4), Easy (5), wired to the SM-2 algorithm above.**Grading and accuracy:** grades 3-5 (Hard, Good, Easy) count as "correct"; grade 1 (Again) counts as "incorrect". Accuracy is calculated per session as `(correct / reviewed) * 100`. This resets on page reload; review progress (intervals, due dates) persists in localStorage. |
|
144
|
|
|
145
|
3. **Spaced repetition queue** — `localStorage`persistence for`{cardId: {n, EF, I, due}}`. **Card ordering:**previously reviewed cards that are due appear first, sorted by due date (most overdue first). New (unseen) cards are**shuffled randomly each session**using**Fisher-Yates shuffle** (the only unbiased O(n) shuffle algorithm — naive`array.sort(() => Math.random() - 0.5)` produces biased distributions). Never present new cards in a fixed order — it creates a false sense of learning tied to sequence rather than recall. |
|
146
|
4. **Session stats** — cards reviewed, accuracy %, cards due tomorrow, total remaining |
|
147
|
|
|
148
|
5. **Card type support** — render Basic Q→A, Cloze (hide blanked terms), and Reversed cards correctly |
|
149
|
6. **Flip animation** — CSS 3D transform, keyboard shortcuts (Space to flip, 1/2/3/4 for grading) |
|
150
|
|
|
151
|
7. **Card difficulty indicators** — show a visual indicator (colored dot or badge) on each card based on its current ease factor. Green for EF ≥ 2.5 (easy), yellow for 1.8 ≤ EF < 2.5 (moderate), red for EF < 1.8 (hard). Helps users see at a glance which cards they're mastering vs. struggling with. |
|
152
|
8. **Leech detection** — track how many times a card has been graded Again (1). If a card is reset more than 4 times, flag it as a "leech" with a visual warning (e.g., a ⚠️ icon). Leeches are almost always malformed cards that should be rewritten, not drilled harder. Optionally offer a "Rewrite this card" prompt. |
|
153
|
|
|
154
|
9. **Daily new card limit** — enforce a configurable daily limit for new (unseen) cards, defaulting to 20. Store the count in localStorage with today's date. Once the limit is reached, only show review cards. This prevents users from overwhelming themselves — the review debt from too many new cards becomes unsustainable by week 3. |
|
155
|
10. **Study streak** — track consecutive days of study in localStorage. Display a streak counter (e.g., "🔥 5-day streak") in the session stats area. A day counts if the user reviews at least 1 card. Streaks reset if a day is missed. Streaks are a proven motivator for building daily review habits. |
|
156
|
|
|
157
|
### Mode 2: AI Quiz |
|
158
|
|
|
159
|
An AI-powered quiz mode that generates and grades questions: |
|
160
|
|
|
161
|
1. **Quiz setup** — user picks a topic (or all topics) and number of questions (5, 10, 20, custom) |
|
162
|
2. **Question generation**— use AI integrations to generate N questions from the card material. Mix question types: multiple choice, short answer, and true/false. Questions should test understanding and application, not just recall.**Difficulty progression:** start with easier recall-level questions and ramp up to application/analysis questions as the quiz progresses. This builds confidence and mirrors real exam structure. |
|
163
|
|
|
164
|
3. **Answer & grade** — user answers each question, then AI grades the response with a score and explanation of what was right/wrong |
|
165
|
4. **Quiz results** — summary screen with overall score, per-question breakdown, and which topics need more work |
|
166
|
|
|
167
|
5. **Weak spot feedback**— highlight topics where the user scored lowest and suggest reviewing those flashcards.**Link back to flashcard mode:** include a "Review these cards" button next to weak topics that switches to flashcard mode pre-filtered to that topic. This closes the learn-test-review loop. |
|
168
|
|
|
169
|
### Mode 3 (Optional): Card Import from Notes |
|
170
|
|
|
171
|
If the user wants to create their own cards, offer a text import mode: |
|
172
|
|
|
173
|
1. **Paste area** — user pastes notes, bullet points, or prose into a text area |
|
174
|
2. **AI card generation** — use AI integrations to parse the text and generate flashcards following Wozniak's minimum information principle. Output Basic Q→A and Cloze cards. |
|
175
|
|
|
176
|
3. **Review before adding** — show the generated cards in an editable list. Let the user approve, edit, or delete each card before adding to the deck. |
|
177
|
4. **Merge into deck** — approved cards get added to the main deck with fresh SM-2 state (n=0, EF=2.5, I=0). |
|
178
|
|
|
179
|
### UI/UX Requirements |
|
180
|
|
|
181
|
- **Tab or toggle** to switch between Flashcard and Quiz modes |
|
182
|
- **Clean, focused design** — one card or question centered on screen, no clutter |
|
183
|
|
|
184
|
- **Mobile-friendly** — responsive layout, touch targets |
|
185
|
- **Topic/deck selector** — filter by topic in both modes |
|
186
|
|
|
187
|
- **Progress indicator** — card counter in flashcard mode, question progress bar in quiz mode |
|
188
|
- **Progress history** — store daily review counts and accuracy in localStorage. Optionally display a simple chart or heatmap showing review activity over the past 30 days. This gives users a sense of long-term progress beyond the current session. |
|
189
|
|
|
190
|
## Best Practices |
|
191
|
|
|
192
|
1. **Minimum information principle trumps everything** — when in doubt, split the card |
|
193
|
2. **Cloze is the default for prose** — fastest path from notes to reviewable cards |
|
194
|
|
|
195
|
3. **Never make set-enumeration cards** — "list all X" → overlapping cloze instead |
|
196
|
4. **30 great cards > 100 mediocre ones** — review burden compounds; every bad card costs minutes over months |
|
197
|
|
|
198
|
5. **Cap new cards at ~20/day** — the review debt from 100 new cards/day becomes unsustainable by week 3 |
|
199
|
6. **Interleave topics in the card data array** — when hardcoding cards, mix topics throughout the array rather than grouping all cards of one topic together. Even with shuffle logic, interleaving ensures better variety if the shuffle ever fails or is bypassed |
|
200
|
|
|
201
|
## Technical Notes |
|
202
|
|
|
203
|
- **Fisher-Yates shuffle implementation:** When shuffling new cards, always use the Fisher-Yates (Knuth) algorithm. The naive `array.sort(() => Math.random() - 0.5)` approach produces biased distributions where some orderings are significantly more likely than others. Correct implementation: |
|
204
|
|
|
205
|
```typescript |
|
206
|
|
|
207
|
function fisherYatesShuffle<T>(arr: T[]): T[] { |
|
208
|
|
|
209
|
const shuffled = [...arr]; |
|
210
|
|
|
211
|
for (let i = shuffled.length - 1; i > 0; i--) { |
|
212
|
|
|
213
|
const j = Math.floor(Math.random() * (i + 1)); |
|
214
|
|
|
215
|
[shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]]; |
|
216
|
|
|
217
|
} |
|
218
|
|
|
219
|
return shuffled; |
|
220
|
|
|
221
|
} |
|
222
|
|
|
223
|
``` |
|
224
|
|
|
225
|
- **localStorage size limits** — localStorage has a ~5MB limit per origin. For small-to-medium decks (<500 cards), this is fine. For large decks (500+ cards) with extensive review history and progress tracking, consider using IndexedDB as a fallback. At minimum, store only essential SM-2 state per card (`{n, EF, I, due, lapses}`) — avoid storing full review logs in localStorage. |
|
226
|
- **React hook ordering** — when implementing the spaced repetition hook, declare all React hooks (`useState`,`useRef`,`useMemo`,`useEffect`) at the top of the function before any conditional logic. Adding hooks between existing hooks during iteration (e.g., inserting a`useRef`between`useMemo` calls) will crash React's HMR during development. The order must be stable across renders. |
|
227
|
|
|
228
|
## Limitations |
|
229
|
|
|
230
|
- Cannot read existing `.apkg` files (genanki is write-only); cannot sync to AnkiWeb |
|
231
|
- Cannot track review history across sessions unless building a persistent app (use localStorage or IndexedDB for client-side persistence) |
|
232
|
|
|
233
|
- Verify generated content for specialized domains — confident-sounding wrong cards are worse than no cards |