{"slug":"teaching-project-vocabulary-builder","title":"Teaching project. Vocabulary builder","date":"2026-02-28T12:18:31.753Z","excerpt":"","tags":["project"],"order":29,"published":true,"content":"

Vocabulary Builder — Full Project Requirements

\n\n

1. Vision

A vocabulary learning system that teaches precision within concepts the learner already understands.

A student already knows \"sad.\" The system teaches them that \"despondent\" means sad with lost hope — a shade of meaning they can now express that they couldn't before.

The system is not a word list. It is a map of human experience, where every cluster represents a domain of life the learner will encounter, and every word is a more precise tool for navigating that domain.

\n\n

2. Word Source

Base list: 1,000 most frequent English content words
Content words only — nouns, verbs, adjectives
No function words, prepositions, articles, or numbers
Reference: Oxford 3000 (A1–A2 band) or equivalent frequency corpus
These 1,000 words become the L1 root words

\n\n

3. Core Architecture — The Semantic Tree

Each L1 root word expands into a semantic tree:

CLUSTER (theme)\n└── L1 root word\n    ├── L2 branch A          ← nuance of L1\n    │   ├── L3 leaf A1       ← nuance of L2 branch A\n    │   └── L3 leaf A2\n    ├── L2 branch B\n    │   ├── L3 leaf B1\n    │   └── L3 leaf B2\n    └── L2 branch C\n        ├── L3 leaf C1\n        └── L3 leaf C2

Rules:

L2 words are nuances of their L1 parent — same general concept, more specific meaning
L3 words are nuances of their L2 parent — even more precise or formal
Trees grow organically — branch count reflects real semantic nuance, not a fixed number
Word class is preserved across the entire tree — a verb stays a verb from L1 to L3
One tree = one word class only

\n\n

4. Word Classes

Verbs, adjectives, and nouns only
Each cluster uses whatever word classes fit naturally — flexible per cluster
Word class preserved across the entire tree — a noun at L1 stays a noun at L2 and L3

\n\n

5. The 15 Clusters

Clusters are the thematic grouping above the tree. They represent the full range of human experience the learner should develop language for, and serve as the unit of progress tracking.

`cluster` value	Display name
`conflict_and_disagreement`	Conflict & Disagreement
`thinking_and_understanding`	Thinking & Understanding
`feeling_and_emotion`	Feeling & Emotion
`helping_and_supporting`	Helping & Supporting
`communication`	Communication
`learning_and_knowledge`	Learning & Knowledge
`work_and_achievement`	Work & Achievement
`health_and_body`	Health & Body
`relationships_and_social`	Relationships & Social Life
`change_and_growth`	Change & Growth
`danger_and_safety`	Danger & Safety
`nature_and_environment`	Nature & Environment
`creativity_and_imagination`	Creativity & Imagination
`decision_and_choice`	Decision & Choice
`movement_and_travel`	Movement & Travel

\n\n

6. The JSON Word Database

Every word stored as a flat JSON array with exactly these fields:

json

[\n  {\n    \"word\": \"sad\",\n    \"level\": 1,\n    \"class\": \"adjective\",\n    \"parent\": null,\n    \"root\": \"sad\",\n    \"cluster\": \"feeling_and_emotion\"\n  },\n  {\n    \"word\": \"unhappy\",\n    \"level\": 2,\n    \"class\": \"adjective\",\n    \"parent\": \"sad\",\n    \"root\": \"sad\",\n    \"cluster\": \"feeling_and_emotion\"\n  },\n  {\n    \"word\": \"gloomy\",\n    \"level\": 2,\n    \"class\": \"adjective\",\n    \"parent\": \"sad\",\n    \"root\": \"sad\",\n    \"cluster\": \"feeling_and_emotion\"\n  },\n  {\n    \"word\": \"miserable\",\n    \"level\": 3,\n    \"class\": \"adjective\",\n    \"parent\": \"unhappy\",\n    \"root\": \"sad\",\n    \"cluster\": \"feeling_and_emotion\"\n  },\n  {\n    \"word\": \"despondent\",\n    \"level\": 3,\n    \"class\": \"adjective\",\n    \"parent\": \"gloomy\",\n    \"root\": \"sad\",\n    \"cluster\": \"feeling_and_emotion\"\n  }\n]\n```\n\n### Field Definitions\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `word` | string | The target word |\n| `level` | integer | 1, 2, or 3 |\n| `class` | string | `\"verb\"`, `\"adjective\"`, or `\"noun\"` |\n| `parent` | string or null | The word this branches from. `null` if L1 |\n| `root` | string | The L1 root word of this tree |\n| `cluster` | string | The thematic cluster in `snake_case` |\n\n### Integrity Rules\n- Every L2 word must reference a valid L1 word as its `parent`\n- Every L3 word must reference a valid L2 word as its `parent`\n- L1 words always have `parent: null`\n- `root` is always the L1 ancestor — same value repeated on every word in the tree\n- No duplicate words within the same cluster\n- `cluster` values in `snake_case`\n\n---\n\n## 7. Scale Estimate\n\n| Level | Count |\n|-------|-------|\n| L1 roots | ~1,000 |\n| L2 branches | ~2,500 |\n| L3 leaves | ~5,000 |\n| **Total** | **~8,500 words** |\n\nCovers: Oxford 3000 ✅ Oxford 5000 ✅ Academic & professional vocabulary ✅\n\n---\n\n## 8. The Production Pipeline\n\nThe system is built in three sequential phases. Each phase must be completed and audited before the next begins.\n```\nPHASE 1 — CONTRACT\nBuild word list → assign words to article slots → audit → lock\n                    ↓\nPHASE 2 — TREE GENERATION (Google AI Studio)\nGenerate L2 and L3 branches for each L1 root → audit → lock\n                    ↓\nPHASE 3 — ARTICLE GENERATION (Google AI Studio)\nGenerate 500 articles × 3 versions using contract + word database

\n\n

Phase 1 — The Contract

The only phase that requires no AI. Built entirely through data engineering — a script or spreadsheet.

The contract pre-assigns every L1 word to article slots before any generation begins. This guarantees that all 1,000 words receive sufficient coverage and that no word is accidentally neglected by the AI.

Assignment rules:

Every word appears in at least 2 articles
No word appears in more than 5 articles
The same word never appears in consecutive articles
The same word appears in different cluster contexts across its appearances
Each article draws its 5 words from at least 2 clusters
No cluster occupies more than 2 slots in any single article

Contract file schema:

json

{\n  \"total_articles\": 500,\n  \"total_word_slots\": 2500,\n  \"articles\": [\n    {\n      \"article_id\": \"001\",\n      \"target_words\": [\"sad\", \"argue\", \"forgive\", \"decide\", \"pain\"]\n    },\n    {\n      \"article_id\": \"002\",\n      \"target_words\": [\"build\", \"proud\", \"fail\", \"team\", \"effort\"]\n    }\n  ],\n  \"word_frequency_map\": {\n    \"sad\":     [\"article_007\", \"article_089\", \"article_234\"],\n    \"argue\":   [\"article_012\", \"article_156\"],\n    \"flat\":    [\"article_034\", \"article_201\", \"article_445\"],\n    \"measure\": [\"article_067\", \"article_312\"]\n  }\n}\n```\n\n**Contract audit checklist before proceeding to Phase 2:**\n```\n✅ All 1,000 words appear at least twice\n✅ No word appears more than 5 times\n✅ No word appears in consecutive articles\n✅ Each article draws from at least 2 clusters\n✅ No cluster dominates more than 2 slots per article\n```\n\n---\n\n### Phase 2 — Tree Generation\n\n**Input:** 1,000 L1 root words from the contract\n**Tool:** Google AI Studio\n**Output:** Complete JSON word database (~8,500 words)\n\nThe AI receives each L1 root word and generates its L2 branches and L3 leaves organically. Output is appended to the word database.\n\n**AI instruction per word:**\n> Given the L1 word, its word class, and its cluster, generate all meaningful L2 nuances and their L3 sub-nuances. Output JSON only. Follow the schema exactly.\n\n**Tree audit checklist before proceeding to Phase 3:**\n```\n✅ Every L2 word has a valid L1 parent\n✅ Every L3 word has a valid L2 parent\n✅ All L1 words have parent: null\n✅ No duplicate words within the same cluster\n✅ Word class is consistent across every tree

\n\n

Phase 3 — Article Generation

Input: Contract file + word database\nTool: Google AI Studio\nOutput: 500 articles × 3 level versions = 1,500 article versions

For each article slot, the AI receives its 5 assigned words plus their L2 and L3 upgrades from the word database. It then writes the article three times.

AI instruction per article:

\n
Write a short, simple story that naturally uses these 5 words. Write it 3 times. In version 1 use the L1 words. In version 2 replace only the 5 target words with their L2 equivalents. In version 3 replace only the 5 target words with their L3 equivalents. Keep all other words identical across all 3 versions.
\n

Article JSON schema:

json

{\n  \"article_id\": \"007\",\n  \"target_words\": [\n    { \"word\": \"sad\",     \"level_shown\": 1, \"root\": \"sad\",     \"cluster\": \"feeling_and_emotion\" },\n    { \"word\": \"argue\",   \"level_shown\": 1, \"root\": \"argue\",   \"cluster\": \"conflict_and_disagreement\" },\n    { \"word\": \"forgive\", \"level_shown\": 1, \"root\": \"forgive\", \"cluster\": \"relationships_and_social\" },\n    { \"word\": \"decide\",  \"level_shown\": 1, \"root\": \"decide\",  \"cluster\": \"decision_and_choice\" },\n    { \"word\": \"pain\",    \"level_shown\": 1, \"root\": \"pain\",    \"cluster\": \"health_and_body\" }\n  ],\n  \"versions\": {\n    \"l1\": \"The man felt sad...\",\n    \"l2\": \"The man felt gloomy...\",\n    \"l3\": \"The man felt despondent...\"\n  }\n}\n```\n\n---\n\n## 9. Student Progress Tracking\n\nProgress is tracked **at the word level**, not the article level. When a student reads an article, every target word updates its cluster progress independently.\n```\nStudent reads article 7\n     ↓\n5 target words identified\n     ↓\nJSON lookup → each word maps to its cluster\n     ↓\n5 cluster progress scores updated simultaneously\n```\n\n### Progress States Per Cluster\n\n| Status | Condition |\n|--------|-----------|\n| **Met** | Student has seen at least one L1 root in this cluster |\n| **Exploring** | Student has encountered L2 branches in this cluster |\n| **Mastering** | Student has reached L3 leaves in this cluster |\n\nProgress is a **coverage map**, not binary. Within a single cluster a student can be Met on some roots, Exploring on others, and Mastering on a few simultaneously.\n\n---\n\n## 10. Recommendation Engine\n\nThe article database sequences itself differently for every learner based on their unique progress map. Two students can read all 500 articles in completely different orders and both achieve full coverage of all 15 human experiences.\n\n### Recommendation Score Formula\n```\nScore = (cluster deficit weight  × 0.5)\n      + (depth needed weight     × 0.3)\n      + (time since last seen    × 0.2)\n```\n\n| Signal | Weight | What it does |\n|--------|--------|--------------|\n| **Cluster deficit** | 50% | Ensures no human experience domain is left behind |\n| **Depth needed** | 30% | Pushes learner deeper into clusters they have only Met |\n| **Time since last seen** | 20% | Resurfaces clusters before the forgetting curve sets in |\n\n### How It Works\n```\n1. Score each cluster by coverage deficit\n2. Identify the 3 most neglected clusters\n3. Find articles whose target words intersect those clusters\n4. Rank articles by how well they fill the gap\n5. Recommend top 3 articles to the learner

What the Learner Sees

\n
\"You've been exploring emotions and conflict a lot. How about a story about making a decision in nature? It touches areas you haven't visited yet.\"
\n

\n\n

11. Educational Rationale

Why semantic trees instead of word lists?\nResearch in second language acquisition (Nation, 2001; Beck et al., 2002) shows that vocabulary is retained significantly better when words are learned in meaningful relationship to each other rather than in isolation. The semantic tree makes those relationships explicit — a learner doesn't just memorize \"despondent,\" they understand it as a specific kind of gloomy, which is itself a specific kind of sad. This layered understanding creates durable, retrievable knowledge.

Why thematic clusters?\nThe brain organizes knowledge in schemas — mental frameworks built around experiences. Teaching vocabulary through thematic clusters mirrors how the brain naturally stores and retrieves language. When a learner encounters \"conflict\" in real life, the whole cluster activates, making related words more accessible.

Why 3 levels?\nThe three levels correspond to well-established proficiency stages. L1 maps to basic communicative competence (CEFR A1–A2), L2 to independent usage (B1–B2), and L3 to precise, educated expression (C1–C2). Moving through the tree is moving through real proficiency, not artificial difficulty.

Why organic branching?\nForcing uniform branch counts would introduce artificial words or omit real nuance. The tree grows where the language actually grows. Some concepts like emotion and conflict are semantically rich and branch widely. Others like physical movement are narrower. The system respects the actual structure of English rather than imposing a grid on it.

Why balanced cluster coverage?\nA learner who only reads about conflict and emotion will develop uneven vocabulary — fluent in some domains of life, silent in others. Balanced coverage across all 15 clusters ensures the learner develops language for the full range of human experience, not just the experiences they happen to find interesting.

Why a contract before generation?\nWithout pre-assignment, AI generation naturally gravitates toward emotionally convenient words and quietly neglects neutral but equally important words like \"measure,\" \"flat,\" or \"divide.\" The contract removes word selection from the AI entirely, guaranteeing deterministic, auditable coverage before a single article is written.

Why spaced repetition in the recommendation engine?\nThe forgetting curve (Ebbinghaus, 1885) shows that memory decays predictably over time without reinforcement. By tracking when each cluster was last encountered and resurfacing it before decay sets in, the system maximizes long-term retention with minimum redundancy.