Vacab Story Gen

Purpose

Produce an original retelling of a classic fairy tale or picture book whose
vocabulary is strictly limited to a user-specified level, so the text is readable
by a learner at that level. The level is defined against either:

• The Chinese compulsory-education English vocabulary standards (小学 / 初中 / 高中), or
• Mainstream English proficiency frameworks: CEFR (A1–C2), Cambridge (YLE/KET/PET/FCE/CAE/CPE),
  TOEFL, and IELTS.

The output story is written in English (the vocabulary standards are English
vocabulary standards). It preserves the source's characters, setting, and plot arc,
but uses only in-level words and level-appropriate grammar.

When to use

• The user requests a story "for a [level] learner" or "at [level] vocabulary".
• The user names a tale/picture book to be rewritten for a given level.
• Do not use for: free creative writing without a stated level, translations
  into Chinese, or non-narrative text generation.

Mandatory inputs (stop if either is missing)

Before any generation, confirm both are present in the user request:

1. Target vocabulary level — e.g. 小学三年级, CEFR A2, 初中, 雅思 6.0,
   KET, 托福 72. If absent, ask the user to specify the exact level and wait.
2. Source tale / picture book — e.g. 《小红帽》, Little Red Riding Hood,
   《棕色的熊，棕色的熊，你在看什么？》, Brown Bear, Brown Bear. If absent, ask
   the user which classic tale or picture book to adapt and wait.

Do not substitute a default level or source. Both are required by design.

Workflow

Step 1 — Resolve the level to a canonical key

Read references/levels.md and map the user's phrasing to one of the canonical
keys: a1, a2, b1, b2, cn_primary, cn_junior, cn_senior. Apply the
alias table (CEFR / Cambridge / TOEFL / IELTS / Chinese grades). If the phrasing is
ambiguous (e.g. just "剑桥" with no exam), ask for clarification before proceeding.

Note the level's grammar & sentence constraints and story-length target
from references/levels.md; these govern how the story is written.

Step 2 — Load the source structure

Read references/source_stories.md. If the named tale is listed, use its plot
beats. If it is a widely known tale not listed, recall its plot from general
knowledge. If it is a copyrighted modern picture book, use only its structural
pattern (never copy original wording) and build an original story on that pattern.
If the source is unfamiliar, ask the user for a one-paragraph synopsis or the
pattern to follow.

Step 3 — Generate the level-constrained story

Write the story in English, observing ALL of the following:

• Vocabulary: use ONLY words present in references/wordlists/{key}.txt. The
  shared allowlists function.txt (grammar words) and irregulars.txt (irregular
  verb forms) and names.txt (tale proper nouns) are always permitted.
• Grammar: follow the level's sentence/tense constraints from references/levels.md.
• Fidelity: keep the source's core characters, setting, and plot arc.
• Beyond-grade words are allowed WITH a Chinese gloss: if a needed word is above
  level and cannot be smoothly replaced, KEEP it but append a Chinese translation in
  parentheses immediately after it (e.g. swan（天鹅）, ugly（丑陋的）). The
  gloss_story.py script automates this in Step 4. Prefer an in-level synonym when one
  reads naturally; otherwise gloss rather than replace.
• Length: aim for the level's target word count.

Write the draft to a file (e.g. deliverables/{source}_{key}.md) so it can be
checked, and also keep it in the response.

Step 4 — Gloss beyond-grade words & verify

Run the gloss script against the draft. It appends a Chinese gloss
(word（中文）) after every word that falls OUTSIDE the target grade's official
vocabulary. The script's "curriculum" = the level wordlist + shared function words +
shared irregular-verb forms. Tale-core words exempted only via names.txt (such as
ugly / swan / duckling) are still treated as beyond-grade and glossed:

python3 {skill}/scripts/gloss_story.py --level {key} --text {draft_file}

• If it reports all beyond-grade words were glossed (exit 0), proceed to delivery.
• If it reports unresolved beyond-grade words (no glossary entry), add them to
  references/glossary.txt (English→Chinese) or replace the word with an in-level
  alternative, then re-run.
• Optionally, also run check_vocab.py for a strict in-level-only view; note that it
  treats names.txt words as allowed, so tale-core words will not appear there.

The story is finished when every word outside the grade list carries a Chinese gloss.

Step 5 — Deliver

Present the final, checker-verified story. Include a short header noting:
- Target level (the user's phrasing and the resolved key),
- Source tale / picture book,
- Word count,
- Any proper nouns allowed via --allow.

Optionally save the final story to deliverables/ in the workspace and present that
file.

Bundled resources

• references/levels.md — level keys, grammar constraints, and the alias→key map.
• references/source_stories.md — plot beats for public-domain tales and
  structure-only patterns for copyrighted picture books.
• references/wordlists/*.txt — allowed-word universe per level (a1, a2,
  b1, b2, cn_primary, cn_junior, cn_senior), plus shared function.txt,
  irregulars.txt, and names.txt.
• scripts/check_vocab.py — verifies a story against a level's wordlist and flags
  out-of-scope words (treats names.txt as allowed).
• scripts/gloss_story.py — appends a Chinese gloss after every word outside the
  target grade's official vocabulary (the core of the beyond-grade handling).
• references/glossary.txt — English→Chinese map used by gloss_story.py for the
  glosses; extend it with any new beyond-grade word you encounter.

Notes & limitations

• 词表来源：cn_primary.txt 现为官方《义务教育英语课程标准(2011年版)》二级词汇表（423 个基本词），
  是权威小学毕业水平词表，非自编估算。a1/a2/b1/b2/cn_junior/cn_senior 仍为精选核心估算集
  （非官方完整大纲）。所有词表均作为允许用词宇宙，可经编辑 .txt 扩展；校验脚本严格执行文件内词。
• "小学年级"口径：课标按一级（≈3–4 年级）/ 二级（≈5–6 年级，小学毕业）分档，不按具体年级
  单列。本技能把"小学 / 小学X年级"统一映射到二级档。若需严格按年级（如一年级≈一级子集）切分，
  请提供《一级词汇表》以建立更细子档。
• Beyond-grade words are permitted WITH a Chinese gloss (word（中文）), not
  rejected. This keeps the story faithful to the source while remaining readable: a
  learner sees the English word AND its meaning. Words inside the grade list are left
  clean. The gloss is applied by gloss_story.py using references/glossary.txt.
• CEFR C1/C2 and top-band TOEFL/IELTS map to the b2 key (the richest band
  provided); state this when such a level is requested.
• Stories are original retellings. For copyrighted picture books, only the structural
  pattern is used — never the original text.