new-flash-card

# Flash Card Deck Generator ## Purpose Creates a flash card deck for the Teacher app at `~/.tutor/modules`. You will interview the user, generate all cards, and write them to disk so the app immediately shows the new deck at http://localhost:3000/flashcards. --- ## Step 1 — Interview Ask these questions **one at a time**, waiting for each answer before proceeding: 1. **Source**: "Based on an existing module, or your own material?" - If **module**: run `ls ~/.tutor/modules/` and list the available modules, then ask "Which module should I base the deck on?" Once answered, read the section markdown files inside that module to extract key concepts, definitions, theorems, and formulas. - If **own material**: ask "Paste your notes or text now and I'll extract the key concepts from it." 2. **Subject**: "What subject category fits best? (math / programming / general)" 3. **Language**: "Should the cards be in English or Persian (Farsi)? (en/fa)" 4. **Card count**: "How many cards would you like? (suggested: 15–25, max 50)" --- ## Step 2 — Propose Sample Cards Before generating the full deck, show **5 sample front/back pairs** that represent the range of concepts you plan to cover. Ask: "Do these look right? Any adjustments to style, depth, or focus before I generate all the cards?" Wait for approval or adjustments before proceeding. --- ## Step 3 — Generate All Cards Write `cards.json` to `~/.tutor/modules/flashcards/{deckId}/cards.json`. ```json [ { "id": "c1", "front": "Term or question (markdown + LaTeX OK)", "back": "Definition or answer (markdown + LaTeX OK)" } ] ``` **Card writing rules**: - **Fronts**: concise — a term to define, a formula to name, or a short question - **Backs**: complete — full definition or worked answer; use `$...$` inline LaTeX and `$$...$$` for block equations where appropriate; use fenced code blocks for code subjects - **Distribution**: mix definition cards, formula recall cards, and concept-application cards; avoid clustering all cards of one type together - **For Persian (`fa`)**: write all prose in Farsi; keep math notation, code, and variable names in standard LTR format; include the English term in parentheses on first use of a technical term - **If from a module**: extract key definitions, theorems, named formulas, algorithm steps, and "gotcha" concepts from the lesson markdown files; do not copy entire paragraphs verbatim onto a card back --- ## Step 4 — Write Config Write `config.json` to `~/.tutor/modules/flashcards/{deckId}/config.json`. ```json { "id": "deck-id-in-kebab-case", "title": "Deck Title", "description": "1–2 sentence description of what the deck covers", "subject": "math | programming | general", "language": "en | fa", "sourceModule": "module-id" } ``` Omit `sourceModule` entirely if the deck was not derived from an existing module. **Subject rules**: - `"math"` for: calculus, algebra, statistics, linear algebra, physics, chemistry - `"programming"` for: any language (Go, Python, Rust, etc.) or CS topics - `"general"` for: history, literature, languages, economics, etc. --- ## Step 5 — File Paths and Duplicate Check All files go in `~/.tutor/modules/flashcards/{deckId}/`: - `config.json` — deck metadata - `cards.json` — all flash cards **Before writing**: run `ls ~/.tutor/modules/flashcards/` and check for an existing directory with the same id. If one exists, append `-2` (or the next available suffix) to pick a unique id. **Create the directory** before writing: ``` ~/.tutor/modules/flashcards/{deckId}/ ``` --- ## Step 6 — Confirm After writing all files, tell the user: - The deck id and title - How many cards were written - "Open http://localhost:3000/flashcards — your new deck should appear immediately." If the dev server isn't running: "Run `tutor start` to start the app." --- ## Content Quality Rules 1. **One concept per card**: each card tests exactly one thing; split compound ideas into separate cards 2. **Fronts must be unambiguous**: a front like "What is it?" is useless — be specific 3. **Backs must be self-contained**: the user shouldn't need outside context to understand the answer 4. **Math**: show the formula cleanly; add a one-line intuition note where it helps recall 5. **Persian lessons**: use clear academic Farsi; for technical terms, include the English term in parentheses on first use 6. **Code examples on backs**: use idiomatic, syntactically correct snippets — keep them short (≤ 10 lines) 7. **Avoid trivia**: prefer cards that reinforce understanding over cards that test memorisation of obscure facts 8. **Card count**: honour the user's requested count; never silently truncate or pad --- ## Example Invocation User: `/new-flash-card` You: "Based on an existing module, or your own material?" User: "Existing module" You: "Here are the available modules: `calc3`, `linear-algebra`, `go-basics`. Which one should I base the deck on?" User: "linear-algebra" You: (reads section files, then) "How many cards would you like? Suggested: 15–25, max 50." User: "20" ...show 5 sample cards, wait for approval, generate all 20, write files.