Writing Study Cards

Writing study cards

Use this before creating cards in Armin so the deck actually produces understanding, not a pile of trivia.

A card (the app calls it a "prompt") is a recurring task you give a future learner. Prompt design is task design. Most of the work is _not_ the wording of the question — it's deciding what counts as "knowing" the material, breaking that into discrete pieces, and wiring those pieces into a prerequisite graph.

The five properties every card must satisfy

Each card you create should be:

1. Focused — one detail at a time. Long questions or answers leave parts unrecalled and make it impossible to tell whether the learner remembered everything. 2. Precise — unambiguous about what it's asking. Vague questions get vague answers. 3. Consistent — the same question produces the same answer every review. Inconsistent answers cause interference and erode memory. (The one deliberate exception: creative prompts — see reference.) 4. Tractable — almost always answerable correctly. If it's not, break it down further or add a cue. 5. Effortful — the answer must be genuinely _retrieved_, not trivially inferred from the wording. A cue should narrow the search, never give the answer away.

If a card is hard to keep focused/consistent/tractable, its scope is almost always too broad. Split it.

Workflow

Copy this checklist and work through it:

- [ ] 1. Define what it means to "know" this material (list the knowings)
- [ ] 2. Classify each knowing: fact / list / procedure / concept / open list / salience
- [ ] 3. Decompose into discrete, focused units (one detail each)
- [ ] 4. Choose a card type per unit
- [ ] 5. Write the cards, applying the five properties
- [ ] 6. Wire prerequisites (foundations -> dependents)
- [ ] 7. Run the litmus tests; revise

1. Define what it means to "know" it

Before writing anything, list what a person who _knows_ this topic can do. For a recipe that might be: knows how to make and store it, knows what stock is and why it matters, knows variations and when to use them. This list is your map; every card traces part of it.

2–3. Classify, then decompose

Resist the urge to economize on card count. The number of "units of raw knowledge" is fixed by the material — writing fewer, coarser cards does not reduce what must be learned, it only makes review harder and less consistent. Write more cards than feels natural. Cards are cheap (10–30s/year each); a coarse card that's vague or intractable is expensive.

Caveat: cards are cheap but not free. For material the learner already finds familiar, write fewer cards — there's less marginal knowledge to capture, and reviewing the obvious is demoralizing.

Match card scale to the learner's existing chunk size: a group of facts that's already a single chunk for them ("Italian aromatics") can be one card; otherwise split into individual facts.

The detailed playbook for each knowledge type — facts, explanation pairs, closed lists (cloze), procedures (keyword extraction), concepts (the five lenses), open lists (tag pattern), salience/behavioral, and creative prompts — lives in reference.md. Read it when classifying and decomposing.

4. Choose a card type

Armin card types and when to reach for each:

Default to basic. Don't cram multiple facts into one card to save types — make more cards instead.

6. Wire prerequisites

This is Armin's core idea: a card stays locked until its prerequisites are learned, so foundations come first. Getting the graph right matters as much as the cards.

Rules for prerequisite edges:

• Make A a prerequisite of B only if you genuinely cannot understand or answer B without already knowing A. "Related" is not enough — the test is _necessity_, not _relevance_.
• Foundations point to dependents. Terms, definitions, and simple facts are prerequisites of explanation, conceptual, integrative, and application cards built on them. The reverse explanation ("_why_ do we use bones?") depends on the plain fact ("bones are used").
• Order from foundations to dependents across the whole deck.
• Keep the graph shallow and meaningful. A handful of real dependencies beats a dense web. Over-linking locks cards that didn't need to be locked.
• No cycles. If two cards each seem to need the other, they're probably one chunk, or the dependency only runs one way.
• When building several related cards at once, prefer import_card_hierarchy: assign stable clientIds and declare prerequisites by clientId in a single call.

Litmus tests (run before finalizing)

• False positives — could the learner answer correctly _without_ knowing the target? Watch for pattern-matching on long/unusual wording (cloze deletions copied from text are prone to this) and cues that give the answer away ("rhymes with parrots").
• False negatives — could someone who _knows_ the material still miss it because the question admits other correct answers? Add just enough context to exclude alternatives without inviting pattern matching. Prefer expressing general knowledge generally over pinning it to one source.
• Avoid binary (yes/no, this/that) questions — they need little effort and produce shallow understanding. Rephrase as open-ended, often by connecting to an example or implication.

Full litmus-test discussion and examples are in reference.md.

In practice

Your job is to turn a given resource into a complete tree of cards the learner can review — not a sampler. The "write a few prompts and iterate" advice meant for a human reading over weeks does not apply to you: you have the whole resource in front of you now, so cover it.

• Cover the resource thoroughly. Walk the "knowings" from step 1 and decompose every meaningful one into cards. Each load-bearing fact, term, relationship, step, and concept the resource teaches should be reachable through some card. Decompose generously — many focused cards beat a few coarse ones.
• But don't pad. Thorough means covering the real units of knowledge, not inventing trivia. Skip the genuinely obvious (common-sense steps, throwaway asides) and details the resource itself treats as incidental. Coverage of what matters, not completionism for its own sake.
• Deliver one connected tree, not a flat pile. Emit the whole deck in a single import_card_hierarchy call with prerequisites wired so foundations unlock dependents. The graph is part of the deliverable; an unconnected list of cards is an incomplete answer.
• Set scope to the learner when known. If told the learner already knows part of the material, write fewer cards there — reviewing the obvious is demoralizing. Absent that signal, assume a motivated beginner and cover the foundations.
• Make every card individually sound. Before finishing, re-check each card against the five properties and the litmus tests. A card that's vague, intractable, or untethered from the tree is worse than no card.

Knowledge-type playbook

How to decompose each kind of knowledge into cards, with worked examples. Examples use a chicken-stock recipe. Map every Q./A. to an Armin card type (basic, basic_reversed, cloze, type_answer, diagram).

Factual knowledge

Raw information with few relationships. Break it into single facts.

Q. What type of chicken parts are used in stock?
A. Bones.

Pair facts with explanation cards when the explanation is interesting or the fact is hard to remember. Explanations make facts meaningful and give them hooks to other ideas. Make the explanation precise:

Q. How do bones produce a chicken stock's rich texture?   (better than "Why do we use bones?")
A. They're full of gelatin.

The explanation card depends on the plain fact — wire it as a dependent.

Closed lists -> cloze

A closed list has a fixed set of members (chicken stock aromatics = onion, carrots, celery, garlic, parsley). Treat it like a complex fact. Don't ask "name all the aromatics" — it's intractable and inconsistent. Use fill-in-the-blank with one blank per review, keeping list order fixed so the learner also learns its shape:

Q. Typical chicken stock aromatics:
- onion
- {{1::carrots}}
- {{2::celery}}
- {{3::garlic}}
- {{4::parsley}}

In Armin this is one cloze card; each number is a separate review. Add a cue when needed — {{4::parsley::herb}} — but never one that trivializes recall ("rhymes with parrots" requires no knowledge of stock). A mnemonic can instead live in the answer/parentheses as an optional aid.

Write per-item explanation cards ("why is carrot a good aromatic?") so the learner can regenerate the list without the cloze scaffolding.

Quantities and interpretation

Writing cards forces interpretation — the first step to understanding beyond the page. Don't ask "how much bone in a batch?" ("batch" is undefined); express the underlying ratio generally:

Q. What's the ratio of chicken bones to water in chicken stock?
A. A quart of water per pound of bones.

Skip quantities that aren't real units ("a bunch of parsley") — just note them informally.

Procedural knowledge -> extract keywords

Procedures are lists, but cloze-deleting whole steps is unfocused. First strip each step to its keywords, then drop steps that are common sense (step 1 "combine ingredients", final "store" — obvious once you know what stock is). Turn the load-bearing keywords into focused questions ("play Jeopardy"):

Q. At what speed should you heat a pot of ingredients for chicken stock?
A. Slowly.

Q. When making chicken stock, what should you do after the pot reaches a simmer?
A. Lower the temperature to a bare simmer.

Q. How long must chicken stock simmer?
A. 90 minutes.

For procedures, capture conditions/heuristics for moving between steps (when to lower heat, how long), not obvious verbs. Add "heads-up" cards (how long heating takes) and explanation cards ("why low heat?" → "brighter, cleaner flavor"). Branching procedures: capture the predicates; if complex, use a diagram. Phrase uncertain answers tentatively and record the source.

Conceptual knowledge -> the five lenses

A concept isn't a definition to parrot; design a set of cards that collectively trace its edges. Use these lenses as a toolkit (you won't need all of them for every concept):

• Attributes and tendencies — what's always / sometimes / never true of it?

Q. Why don't stocks usually have a distinctive flavor? A. To stay versatile.

• Similarities and differences — what distinguishes it from adjacent concepts?

Q. How is stock different from soup broth? A. Broth has a complete flavor; stock isn't meant to stand alone.

• Parts and wholes — examples, sub-concepts, the broader category it belongs to.

Q. Name at least three examples of stock. A. e.g. chicken, vegetable, mushroom, pork.

• Causes and effects — what does it do, why, and when is it used?

Q. Why do restaurants use stock instead of water? (two reasons) A. Adds flavor; improves texture.

• Significance and implications — why it matters; make it personally meaningful.

Q. What liquid building block explains why simple restaurant dishes beat home renditions? A. Stock.

A term↔definition pair fits basic_reversed, but pairing alone is not "knowing the concept" — add lens cards.

Open lists -> the tag pattern

An open list grows forever (ways to use chicken stock); you don't memorize it. Treat it like a tag and write three kinds of cards:

1. Instance -> tag (the workhorse): Q. When puréeing vegetables for soup, how can you add richness without fat? A. Thin with chicken stock instead of water. 2. A pattern in the tag: Q. What should you ask yourself when using water in savory cooking? A. "Should I use stock instead?" 3. Fuzzy tag -> examples (only works alongside the above): Q. Name two ways to use chicken stock. A. e.g. cook grains, steam greens, purée soups, deglaze pans.

The third card alone fails the consistency property; it needs the instance cards behind it.

Salience and behavioral prompts

Some cards exist not to _know_ a fact but to keep an idea top of mind until it connects to real life (extending the "Baader-Meinhof" effect on purpose). Phrase them around the situation where the idea should fire:

Q. What should you do with the carcass of a roast chicken?
A. Freeze it and make stock.

Q. To keep the freezer stocked, what should you buy instead of chicken parts?
A. Whole birds.

Context-laden, situation-anchored phrasing helps knowledge transfer from theory to practice.

Creative prompts (the consistency exception)

When a concept applies to many instances, a card can ask for a _new_ answer each time:

Q. Name a vegetable purée soup to try with chicken stock (one you haven't named before).
A. e.g. potato, parsnip, celeriac, sunchoke, squash, carrot, lentil...

This deliberately breaks consistency — the goal is generation, not retrieval. It only works once the learner has enough grounding to produce varied answers, so it belongs downstream of the foundational cards (a dependent in the graph). Use sparingly; its effects are less understood than retrieval cards.

Litmus tests

False positives — answerable without knowing

• Discourage pattern matching. Long questions with unusual wording get memorized by shape. Keep questions short; be wary of cloze deletions copied verbatim from a text.
• Don't give the answer away in a cue. "Rhymes with parrots" → carrots needs no knowledge of stock. A good cue ("herb") narrows the field but leaves retrieval work.

False negatives — knowing but failing to answer

Usually caused by too little context, so other answers are equally valid. "What's the first step to cook an omelette?" has many right answers six months later. Add enough context to exclude alternatives — but express general knowledge generally rather than pinning it to one provincial source:

Bad:  What's the first step in the Bon Appétit Jun '18 omelette recipe?
Good: When making an omelette, how must the pan be prepared before adding the eggs?

A card that doesn't exclude alternatives forces the learner to also memorize "what the question is asking" — a smell.

Avoid binary questions

Yes/no and this/that questions take little effort and produce shallow understanding. Connect to an example or implication instead:

Bad:  Does chicken stock make vegetables taste like chicken?  -> No.
Good: How does chicken stock affect the flavor of vegetable dishes?  -> Makes them taste more "complete."