How we label study cards — the untangling decision

What happened. In WordSense, everything a learner studies is a "card". Behind the scenes every card carries two labels at once. One says what kind of content it shows — a word meaning, a spelling variant, a phrase, an alphabet letter. The other says where its database row sits in a word's family tree — the whole dictionary word at the top, one meaning of it underneath, one spelling of that meaning underneath that. The two labeling systems grew up separately. Last round you said they look redundant, and that a future vocabulary deck would need its own full tree.

What we did. We cross-checked all 21 possible combinations of the two labels against what our documents promise and what the running app actually does. You were largely right — the labels overlap heavily, though not completely. We also found 12 places where our own documents contradict each other or contradict the app.

What we're deciding. Whether to untangle the two labeling systems now, and if so which of two ways (question M1 — the big one). Plus follow-on rulings: how a vocabulary deck should be structured (M2), whether a dictionary headword can itself be a study card (M3), where the proposed "Passage card" fits (M4, A4), how to fix the 12 document conflicts (M6), and how to keep our master list of official documents from going stale again (M5).

What changes depending on your answers. Nothing a learner sees today, and no learner progress data is touched. This is foundation work: your answers decide how cheap or expensive it is to add the next card types (vocabulary decks, passage cards) and how much confusion future work inherits. Doing it now, before launch, is cheap. Every new card type built on the tangled version raises the price.

The words this page uses

CA ("Card Archetype") — the what-it-shows label. CA1 = one meaning of a word. CA2 = a spelling variant (e.g. "running" under "run"). CA3 = a phrase. CA4 = a plain vocabulary pair, like tech jargon (future). CA5 = an alphabet letter. CA6 = a formatted passage revealed section by section (proposed, not built).

CT ("Card Tier") — the where-it-sits label. CT1 = the dictionary headword itself (also called a lemma — e.g. "run"). CT2 = one meaning of it ("run" = manage a business). CT3 = one spelling/inflection of that meaning ("running").

FSRS — the scheduling engine that decides when each card comes back for review. It never reads either label, which is why this cleanup can't damage anyone's learning progress.

t070 / t310 — database tables. t070 holds the cards; t310 holds each learner's per-card progress. t310 (the protected learner data) is untouched by everything on this page.

ADR-NNN — a numbered written decision record. ADR-081 (3 weeks old) decided to store the what-it-shows label in its own database column. ADR-082 proposes the new Passage card. ADR-057 is an old, retired design doc that keeps getting cited by mistake.

F1–F12 — the twelve document conflicts found this round, listed in section 2d.

The registry — our master list of "which document is the official truth for what" (a file called _CANONICAL-DOCS.md). It has itself gone stale; question M5 asks how to keep it alive.

CP-005 — an earlier review page like this one; some of your answers from it are quoted below. TERMINOLOGY — the project glossary document. Shape α / Shape β — the two candidate ways to untangle the labels, explained in section 3.

1a · Card Archetypes (CA) — what the card shows

These are display labels only — in code, every card is the same kind of thing; the label just decides what content it shows and which screen renders it. Each card row stores its label in one database column (values in use today: lemma | sense | form | script_unit; reserved for later: phrase | vocab; proposed: passage).

1b · Card Tiers (CT) — where the row sits in the word-family tree

The "parent" column is how a row points to the row above it in the tree: a spelling variant points at its meaning, a meaning points at its headword, the headword points at nothing. Numbering starts at 1 by your earlier ruling, and this axis deliberately uses no plant-metaphor names (per your CP-002/CP-009 answers).

How to read this: 8 of the 21 cells are gaps or fuzz. The three solid pairings — meaning-card↔meaning-tier, spelling-variant-card↔variant-tier, headword↔headword-tier — are exactly your redundancy claim: for those, the two labels say the same thing twice. Every other card kind (phrase, alphabet letter, passage, future vocab) sits at the meaning tier, so today the "what it shows" label really works as "which flavor of meaning-tier card is this", plus two labels that just mirror the tier.

Meaning, phrase, and alphabet-letter cards: everything works — grading, graduating to "learned", demotion, all manual levers. Discarding a meaning also cascades to its spelling-variant children.

Spelling-variant cards: the grading behavior is designed and covered by automated tests, but no live screen ever calls it. In practice the only things that happen to a variant row today are being displayed on its parent, and being retired when its parent is discarded.

Passage cards: by design, identical to a meaning card — nothing new.

Headword rows: created directly when a learner's profile is set up, skipping the normal candidate pipeline — and no learner action anywhere is defined for them.

The two ways to untangle it — not resolved, that's question M1

Both are coherent; neither is obviously wrong. Picking one (or neither) is item M1 below.

What has to be touched under either shape: the data-quality checker's rules for which fields each card kind needs; a handful of code constants and the places that stamp the label onto new cards; the screen-routing logic that picks which display a card opens; and every document sentence describing the old labels. What is guaranteed untouched: the scheduling engine, the learner-progress table, and the review endpoints — none of them ever read this label (verified in the Passage-card analysis and a code audit).

Bottom line: cheap now, pricier later. No learner data is touched, the card catalog can be regenerated, and pre-launch rules let us change the database freely. The two real costs are honesty (openly superseding a 3-week-old decision rather than quietly editing it) and a documentation sweep. Every new card type shipped on the tangled version — Passage cards, vocab decks — raises the price of untangling afterward.

The problem: we keep one master list saying "for each topic, THIS document is the official truth". Finding F10 proved the list has gone stale — it still names a retired document as official, and its own "last checked" date is over a month old. A stale master list quietly misleads every agent that consults it. Three ways to keep it alive:

W4-A — Self-updating list. Each official document declares itself official in its own header; a script rebuilds the master list automatically. About half a day of work. Risk: the staleness just moves down a layer — now the headers can rot instead.

W4-B — Weekly check (recommended). Extend the existing weekly audit to compare the list against reality and raise a flag on any mismatch — this would have caught the retired-document row. Small effort. Risk: it detects staleness after the fact rather than preventing it.

W4-C — Ask at write time. The document-writing tool asks "should this be on the official list?" whenever an official-looking document is created. Small effort. Risk: catches new additions only — not retirements, and a retirement is what actually bit us.