jlpt-doan-van-vua

name: jlpt-doan-van-vua description: > Generate JLPT "đoạn văn vừa" (medium-passage / 中文読解) reading comprehension passages as styled HTML files and output CSV training data for AI fine-tuning. Each passage is a medium-length Japanese prose text (250–620 characters depending on level) testing the learner's ability to understand causal relations, reasoning, author's ideas, reference phrases, and key vocabulary via 2-3 multiple-choice questions per passage (N1/N2/N5 = 2 câu, N3/N4 = 3 câu). Skill này bao gồm TOÀN BỘ luồng: gen → QC loop (checklist PASS/FAIL) → sửa. Gen từng bài một, kiểm tra đến khi đạt chất lượng mới chuyển sang bài tiếp theo. Output chỉ gồm HTML + CSV (không có screenshot PNG). Skill này chỉ dành riêng cho dạng "đoạn văn vừa" (中文読解). Use this skill whenever the user wants to: gen bài đoạn văn vừa, tạo nội dung đoạn văn vừa, generate medium-passage reading comprehension, create JLPT 中文 passages, produce AI fine-tuning data for the đoạn văn vừa section of JLPT N1-N5, kiểm tra chất lượng, quality check, review bài, QC. Also trigger when the user mentions: gen bài đoạn văn vừa, tạo medium passage, generate JLPT 中文読解, medium reading passage N1/N2/N3/N4/N5.

JLPT 中文 / Đoạn Văn Vừa — Workflow

🔒 NGUYÊN TẮC CỐT LÕI — ZERO-TOLERANCE (BẮT BUỘC):

1. Gen từng bài một — không batch rồi QC sau
2. Agent tự QC — đọc lại bài + câu hỏi, tự đánh giá từng mục, log PASS/FAIL
3. 🚨 1 FAIL = CHƯA XONG — sửa → QC lại TỪ ĐẦU → lặp đến khi ALL PASS. TUYỆT ĐỐI CẤM:
   • Skip mục FAIL hoặc mark "tạm thời để đó"
   • Tự ý sang bài tiếp khi còn ≥ 1 FAIL ở bài hiện tại
   • Ghi PASS mà không thực sự đọc lại nội dung và verify
   • "Hợp lý hoá" lỗi (vd "char count chỉ vượt 5 ký tự thì OK") — nếu rule nói FAIL thì là FAIL
4. 🔒 5 GATE bắt buộc giữa các BƯỚC (0→1, 1→2, 2→3, 3→4, 4→5) — KHÔNG qua gate = KHÔNG được sang bước tiếp. Mỗi gate phải log explicit "GATE X→Y PASSED" trước khi tiếp tục.

Cấu trúc file

Outputs Per Passage

1. Styled HTML → assets/html/doan_van_vua/{LEVEL}_{uuid}.html
2. Clean HTML → CSV column text_read (no attributes, no <rt> content)
3. CSV row → sheets/samples_v1.csv với 2-3 câu hỏi populate (slot còn lại empty)

KHÔNG có screenshot PNG. CSV column general_image luôn "".

Số câu hỏi per level (BẮT BUỘC)

⛔ COVERAGE RULE: 2-3 câu hỏi trong 1 bài PHẢI test các đoạn/ý KHÁC NHAU, không được trùng phủ 1 đoạn. ⛔ LABEL DIVERSITY: ≥ 2 label khác nhau trong 1 bài (ngoại lệ: N5 có thể 2 question_content_match).

WORKFLOW

BƯỚC 0: CHUẨN BỊ (1 lần cho batch)

1. Đọc rules/rule_doc_hieu.md — Bộ Tiêu Chí Đánh Giá Đọc Hiểu JLPT toàn diện từ giáo viên (source-of-truth, 11 phần: 4 tiêu chí, 程度 ±, 書き下ろし/による, ①② 下線 空欄 注 ※, 文体の統一 (thể chia), furigana per level, 8 loại câu hỏi, 7 loại bẫy (5 chuẩn + Single-side cho 統合理解 + Peripheral Source cho N1), tiêu chí chi tiết per level). Phần áp dụng trực tiếp cho dạng đoạn văn vừa (中文):
   • Phần 1 (Tổng quan & Nguyên tắc 程度) — biên ± per level
   • Phần 2 (Hình thức) — phân bổ ①② 下線 注 theo dạng bài; N4 中文 bắt đầu có ①②
   • Phần 2.4 (Thể chia nhất quán 文体の統一) — N1/N2/N3 dùng 普通形 (だ・である); N4/N5 dùng ます形 (です・ます). Văn bản + câu hỏi + 4 đáp án phải thống nhất thể chia. N5 thêm わかち書き (khoảng trắng giữa các cụm từ).
   • Phần 2.5 (Khoảng cách わかち書き) — Chỉ N5 dùng. N5 BẮT BUỘC dùng 全角スペース (U+3000), CẤM 半角スペース (U+0020). N4-N1 KHÔNG dùng wakachi-gaki.
   • Phần 3 (Furigana — Quy tắc A/B/C) — A: bắt buộc <ruby> tag; B: rắc toàn từ, KHÔNG rắc 1 phần (vd: <ruby>確証<rt>かくしょう</rt></ruby> chứ KHÔNG 確<ruby>証<rt>しょう</rt></ruby>); C: chỉ lần đầu xuất hiện, kể cả 注.
   • Phần 5.8 (Dấu 。 cuối lựa chọn) — Câu hoàn chỉnh (kết bằng である/だ/です/べきだ) → cần 。. Mệnh đề phụ (kết bằng から/ため/ので) hoặc danh từ kanji-ending → KHÔNG 。. 4 options trong 1 Q phải nhất quán.
   • Phần 3 (Furigana) — bảng quy tắc per level
   • Phần 4 (8 loại câu hỏi) — đặc biệt content_match, reference, reason_explanation, content_mismatch (N3), author_opinion (N2), fill_in (N1/N2)
   • Phần 5 (7 loại bẫy = 5 chuẩn + Single-side + Peripheral Source)
   • Phần 6.2 (N5 中文), Phần 7.2 (N4 中文), Phần 8.2 (N3 中文), Phần 9.2 (N2 中文), Phần 10.2 (N1 中文) — tiêu chí chi tiết 4 chiều cho từng level
   • Phần 11 (Bảng so sánh tổng hợp) — tra cứu nhanh.
2. Đọc rules skill: rules/content.md + rules/vocabulary.md + rules/technical.md + rules/questions.md
3. Đọc rules/kanji_jlpt_sensei.csv — dùng để tra level từng kanji khi quyết định furigana
4. Scan sheets/samples_v1.csv và data/doan_van_vua_n*_clean.json — xem format, topic đã dùng → chọn format chưa/ít dùng
5. Load 2-3 sample calibrate style:

   python3 .claude/skills/jlpt-reading-medium-passage/scripts/load_references.py --level N3 --count 3
   

6. Lập kế hoạch batch: mỗi bài gán format + topic + combo question_label khác nhau theo distribution của level. Topic chọn tiếng Anh từ cột en của rules/topic.json (đa dạng ≥ 3 category trong batch > 5 bài).

🔒 GATE 0→1 — KHÔNG QUA = KHÔNG ĐƯỢC GEN

Trước khi bắt đầu BƯỚC 1, agent PHẢI confirm bằng cách tick từng item:

• Đã đọc rules/rule_doc_hieu.md (đặc biệt Phần 1, 2, 2.4 thể chia, 3, 4, 5, các phần per-level applicable, 11)
• Đã đọc đủ 4 file: rules/content.md + rules/vocabulary.md + rules/technical.md + rules/questions.md
• Đã đọc rules/kanji_jlpt_sensei.csv (sẵn sàng tra furigana)
• Đã chạy load_references.py --level {LEVEL} --count 2 và đọc samples
• Đã scan sheets/samples_v1.csv để biết topic + label đã dùng
• Đã có kế hoạch batch (format + topic + label per bài)

❌ Bất kỳ item nào CHƯA tick → quay lại BƯỚC 0, KHÔNG được gen. ✅ Khi 6/6 tick → log GATE 0→1 PASSED — ready to gen rồi sang BƯỚC 1.

BƯỚC 1→5: LẶP CHO TỪNG BÀI

BƯỚC 1: GEN HTML + CÁC CÂU HỎI

Đọc: rules/content.md + rules/vocabulary.md + rules/technical.md + rules/questions.md Tham khảo: references/html-patterns.md cho template per level

1. Gen _id = {LEVEL}_{uuid.uuid4().hex} (full 32-char hex)
2. Chọn format từ R7 (rules/content.md) — 6 formats: essay/anecdote/advice/article/letter/diary.
3. Chọn tag (topic) — tiếng Anh từ cột en của rules/topic.json, đa dạng trong batch
4. Chọn combo question_label theo level (R5):
   • N1 (2 câu): 1 question_fill_in_the_blank + 1 question_reason_explanation/question_author_opinion
   • N2 (2 câu): 1 question_reference (marker ①) + 1 question_reason_explanation/question_author_opinion
   • N3 (3 câu): 1 question_reference + 1 question_reason_explanation + 1 question_content_match
   • N4 (3 câu): 2 question_content_match + 1 question_reference/question_reason_explanation
   • N5 (2 câu): 2 question_content_match, HOẶC 1 question_content_match + 1 question_reference
5. Gen HTML theo rules → save assets/html/doan_van_vua/{LEVEL}_{uuid}.html
   • Container max-width: 720px; margin: 0 auto
   • word-break: keep-all (đảm bảo xuống dòng sạch ở ranh giới từ)
   • <p> thuần, không <br> giữa câu (trừ N5 letter/diary)
   • Marker ①②③ khớp với các câu hỏi question_reference/question_fill_in_the_blank
   • Furigana chỉ cho từ vượt level (tra rules/kanji_jlpt_sensei.csv)
   • Minimum 3 paragraph cho N1-N4 (cần đủ nội dung cho multi-question)
6. Gen 2-3 câu hỏi + 4 đáp án mỗi câu theo rules/questions.md:
   • 4 options ngăn cách \n, KHÔNG số thứ tự 1., ①, 1)
   • correct_answer_i = integer 1-4
   • Mỗi distractor PHẢI dùng info/ý THẬT từ bài (1 trong 6 loại bẫy: Reversal/Detail swap/Scope/Misinterpretation/Part of truth/Over-generalization)
   • Giải thích explain_vn_i + explain_en_i theo format 3 phần
7. [BẮT BUỘC] Auto-check furigana ngay sau khi save HTML — chạy:

   python3 .claude/skills/jlpt-reading-medium-passage/scripts/check_furigana.py \
     --file assets/html/doan_van_vua/{LEVEL}_{uuid}.html \
     --level {LEVEL} \
     --csv rules/kanji_jlpt_sensei.csv
   

   • Nếu báo MISSING FURIGANA → BẮT BUỘC thêm <ruby><rt> cho mỗi kanji bị thiếu, KHÔNG sang bước Q+A.
   • Nếu báo REDUNDANT FURIGANA → cân nhắc bỏ ruby thừa (kanji ≤ level không cần furigana).
   • Nếu báo UNKNOWN KANJI → tra cứu kanji hiếm, thường cần ruby ở mọi level.
   • Chỉ khi script chạy không có MISSING FURIGANA → mới sang bước tạo CSV.
8. Tạo CSV row bằng process_html.py hoặc fill_qa.py (⚠️ dùng script, KHÔNG sửa CSV tay):

   # Recommended cho multi-question: JSON
   python3 .claude/skills/jlpt-reading-medium-passage/scripts/process_html.py \
     --file assets/html/doan_van_vua/{LEVEL}_{uuid}.html \
     --csv sheets/samples_v1.csv \
     --tag "{topic_vn}" \
     --questions-json /tmp/qs.json
   

   Hoặc dùng fill_qa.py với flags per-question:

   ⛔ KHÔNG ĐƯỢC sửa CSV bằng tay. Commas + newlines trong nội dung (100,000円, A\nB\nC\nD) sẽ làm vỡ cột.

   python3 .claude/skills/jlpt-reading-medium-passage/scripts/fill_qa.py \
     --csv sheets/samples_v1.csv --row-id {LEVEL}_{uuid} --level N3 \
     --q1-label question_reference --q1 "..." --a1 "A\nB\nC\nD" --ca1 2 --evn1 "..." --een1 "..." \
     --q2-label question_reason_explanation --q2 "..." --a2 "A\nB\nC\nD" --ca2 3 --evn2 "..." --een2 "..." \
     --q3-label question_content_match --q3 "..." --a3 "A\nB\nC\nD" --ca3 1 --evn3 "..." --een3 "..."
   

🔒 GATE 1→2 — KHÔNG QUA = KHÔNG ĐƯỢC QC

Trước khi sang BƯỚC 2 (QC), agent PHẢI confirm:

• File HTML đã save vào assets/html/doan_van_vua/{LEVEL}_{uuid}.html (verify file tồn tại)
• CSV row đã tạo bằng process_html.py (KHÔNG sửa CSV tay)
• _id đúng format {LEVEL}_{uuid32} (không tạm thời, không placeholder)
• Tất cả Q + 4 đáp án + correct_answer + explain_vn + explain_en đã fill (không "TODO", không empty)
• Đã đọc lại file HTML vừa gen (mở file, đọc content) — KHÔNG dựa vào "tôi nhớ tôi đã gen"
• Đã chạy check_furigana.py --file ... --level ... --csv rules/kanji_jlpt_sensei.csv và KHÔNG có MISSING FURIGANA — auto-check bắt buộc, log output
• Đã chạy check_csv_fields.py --csv sheets/samples_v1.csv --kind medium và row mới ALL ROWS VALID — auto-check required fields (_id, level, tag, kind, question_label_*, Q slots)
• Đã chạy check_spacing.py --file ... --level ... và spacing OK — N5 BẮT BUỘC わかち書き (ratio ≥ 3%), N1-N4 BẮT BUỘC không có space giữa kanji/kana (ratio ≤ 0.5%)

❌ Bất kỳ item nào CHƯA confirm → quay lại BƯỚC 1 fix, KHÔNG được QC. ✅ Khi 8/8 tick → log GATE 1→2 PASSED — ready to QC rồi sang BƯỚC 2.

BƯỚC 2: ⛔ QC — AGENT TỰ ĐÁNH GIÁ CHECKLIST

ĐÂY LÀ BƯỚC QUAN TRỌNG NHẤT. KHÔNG ĐƯỢC BỎ QUA.

Agent phải đọc lại file HTML vừa gen + TOÀN BỘ câu hỏi/đáp án trong CSV, rồi tự đánh giá từng mục bên dưới. Log kết quả theo format:

QC: {_id}  |  Level: N3  |  Q count: 3/3  |  Labels: [reference, reason, content_match]
────────────────────────────────
[ 1] ✅ PASS — Char count (425 chars, range 380-500)
[ 2] ❌ FAIL — Flow text (found 2x 。<br>)
[ 3] ✅ PASS — Container CSS (720px, margin auto)
...
────────────────────────────────
⚠️ 1 FAIL → sửa rồi QC lại

⛔ KHÔNG ĐƯỢC tự PASS mà không đọc lại nội dung. Phải confirm từng mục cho TẤT CẢ câu hỏi.

🔒 GATE 2→3 — KHÔNG QUA = KHÔNG ĐƯỢC ĐÁNH GIÁ CHECKLIST

Trước khi vào BƯỚC 3 (đánh giá 30 mục checklist), agent PHẢI cam kết:

• TÔI SẼ kiểm tra ĐẦY ĐỦ 30 mục — không skip, không "tạm bỏ qua", không "mục này hiển nhiên PASS"
• TÔI SẼ đọc lại HTML + CSV thực tế trước khi tick mục — KHÔNG dựa vào "tôi đoán/nhớ"
• TÔI SẼ log explicit PASS/FAIL cho từng mục với evidence (số ký tự, dòng nội dung, trích dẫn)
• TÔI SẼ KHÔNG markup hàng loạt PASS — phải đánh giá độc lập từng mục
• TÔI SẼ đặc biệt cẩn thận mục self-solve (BẮT BUỘC giải lại bài từ đầu, không nhìn correct_answer)

❌ Bất kỳ cam kết nào CHƯA tick → quay lại BƯỚC 2 (đọc lại checklist instructions). ✅ Khi 5/5 tick → log GATE 2→3 PASSED — bắt đầu đánh giá 30 mục checklist.

BƯỚC 3: ⛔ CHECKLIST — TẤT CẢ PHẢI PASS

Quy tắc: 1 FAIL = chưa xong. Sửa → QC lại từ đầu → lặp đến khi ALL PASS. Tổng: 34 checks (30 manual + 4 auto-script) ở 4 phần (A HTML, B content, C questions/answers + C2 verify, D multi-question coverage).

PHẦN 0: AUTO-CHECK SCRIPTS — 3 checks BẮT BUỘC chạy đầu tiên

🔒 BẮT BUỘC chạy 3 script trước khi đánh giá manual checklist. Nếu BẤT KỲ script nào FAIL → quay lại BƯỚC 4 sửa, KHÔNG đánh giá tiếp các mục manual.

CẤM bỏ qua 3 mục này — đây là enforce mạnh nhất. Auto-scripts không thể đoán → phải pass thực sự.

PHẦN A: HTML (10 checks)

Agent đọc lại file HTML và kiểm tra:

PHẦN B: NỘI DUNG & TỪ VỰNG (6 checks)

PHẦN C: CÂU HỎI & ĐÁP ÁN (10 checks — áp dụng cho TỪNG câu hỏi)

Agent đọc TOÀN BỘ câu hỏi + 4 đáp án từ CSV và đánh giá từng câu (Q1, Q2, Q3 nếu có):

PHẦN C2: VERIFY ĐÁP ÁN (⛔ QUAN TRỌNG NHẤT) — 2 checks

Agent tự giải từng câu từ đầu — KHÔNG nhìn đáp án đã gen. Đây là bước bắt lỗi distractor bịa, câu hỏi ambiguous, sai correct_answer.

PHẦN D: MULTI-QUESTION COVERAGE — 2 checks

Đặc biệt riêng cho đoạn văn vừa: 2-3 câu hỏi phải test các đoạn/ý khác nhau.

🔒 GATE 3→4 — KHÔNG QUA = KHÔNG ĐƯỢC SỬA

Sau khi đánh giá 30 mục, agent PHẢI confirm trước khi vào fix loop:

• Đã hoàn tất đánh giá ĐẦY ĐỦ 30/30 mục (không thiếu mục nào)
• Đã liệt kê chính xác danh sách các mục FAIL (số mục + lý do FAIL)
• Mỗi FAIL có diagnosis cụ thể (sửa cái gì, ở đâu, theo rule nào)
• Phân biệt rõ fix HTML (cần --refresh CSV sau) vs fix CSV (chỉ cần fill_qa.py) vs fix Q&A logic (gen lại distractor)

🚨 LƯU Ý ĐẶC BIỆT:

• Nếu ≥ 50% mục FAIL → bài này hỏng tổng thể → GEN LẠI TỪ ĐẦU (giữ _id), KHÔNG fix vá
• Nếu mục #25/#26 (self-solve) FAIL → đáp án có vấn đề logic → BẮT BUỘC review lại bài + Q+A, có thể GEN LẠI
• Nếu char count FAIL > Hard Reject → GEN LẠI HOÀN TOÀN (giữ _id)

❌ Bất kỳ item nào CHƯA tick → quay lại BƯỚC 3 đánh giá lại. ✅ Khi 4/4 tick → log GATE 3→4 PASSED — fix list: [#x, #y, #z] với diagnoses rồi sang BƯỚC 4.

BƯỚC 4: SỬA & LẶP LẠI

⛔ Khi sửa HTML, CẬP NHẬT CSV — chạy lại process_html.py --refresh để cập nhật text_read, jp_char_count trong CSV.

🚨 ĐẶC BIỆT khi sửa <ruby> thiếu/rỗng <rt>: Đây là lỗi PHỔ BIẾN — agent hay chỉ sửa HTML mà QUÊN refresh CSV → CSV cột text_read vẫn chứa ruby hỏng → AI fine-tuning data BỊ HỎNG. Workflow BẮT BUỘC khi sửa ruby:

1. Sửa HTML: thay <ruby>興味</ruby> → <ruby>興味<rt>きょうみ</rt></ruby>
2. BẮT BUỘC chạy: python3 .claude/skills/jlpt-reading-medium-passage/scripts/process_html.py --refresh --html-dir assets/html/doan_van_vua --csv sheets/samples_v1.csv
3. Verify: python3 .claude/skills/jlpt-reading-medium-passage/scripts/process_html.py --validate --html-dir assets/html/doan_van_vua --csv sheets/samples_v1.csv — output PHẢI có dòng ✅ CSV ...: 0 row với broken ruby. Nếu vẫn báo 🚫 CSV ... có N row với broken ruby → CSV chưa sync, chạy lại --refresh.

Không có screenshot nên KHÔNG cần chạy lại screenshot script.

Lệnh refresh CSV sau khi sửa HTML:

Lệnh auto-check furigana sau khi sửa ruby:

python3 .claude/skills/jlpt-reading-medium-passage/scripts/check_furigana.py --file <file.html> --level <LEVEL> --csv rules/kanji_jlpt_sensei.csv

Output PHẢI không có MISSING FURIGANA. Nếu còn → sửa tiếp ruby.

python3 .claude/skills/jlpt-reading-medium-passage/scripts/process_html.py \
  --refresh \
  --file assets/html/doan_van_vua/{LEVEL}_{uuid}.html \
  --csv sheets/samples_v1.csv

Vòng lặp BẮT BUỘC: sửa → refresh CSV (nếu sửa HTML) → quay lại BƯỚC 2 (QC lại TẤT CẢ 30 mục TỪ ĐẦU, KHÔNG chỉ check mục đã FAIL) → nếu còn FAIL thì lặp lại. Tối đa 5 vòng. Sau 5 vòng vẫn FAIL → báo lỗi cho user, KHÔNG bỏ qua, KHÔNG sang bài tiếp.

🚨 CẤM TUYỆT ĐỐI:

• Mark "đủ tốt rồi" khi còn ≥ 1 FAIL
• Bỏ qua mục FAIL với lý do "minor"
• Sang bài tiếp khi bài hiện tại chưa ALL PASS
• QC lại chỉ mục đã sửa mà không check lại 30 mục (vì sửa 1 chỗ có thể làm vỡ chỗ khác)

🔒 GATE 4→5 — KHÔNG QUA = KHÔNG ĐƯỢC HOÀN THÀNH

Trước khi log "ALL PASSED", agent PHẢI confirm:

• Đã chạy QC checklist 34 mục TRỌN VẸN (gồm 4 auto-script + 30 manual) ở vòng cuối (không skip)
• TẤT CẢ 34/34 mục đều PASS — bao gồm 4 auto-script đều exit 0 (không có FAIL nào, không có "skip", không có "n/a")
• Nếu có sửa HTML trong loop → đã chạy process_html.py --refresh để sync CSV
• Đã chạy process_html.py --validate cho file hiện tại — KHÔNG có broken ruby trong cả HTML lẫn CSV
• Self-solve thực sự thực hiện: agent tự giải bài + chọn đáp án mà không nhìn correct_answer → KHỚP

❌ Bất kỳ item nào CHƯA tick → quay lại BƯỚC 4 sửa tiếp. ✅ Khi 5/5 tick → cho phép sang BƯỚC 5.

BƯỚC 5: ✅ HOÀN THÀNH → BÀI TIẾP THEO

Chỉ khi TẤT CẢ 33 checks PASS + GATE 4→5 PASSED → log:

🎉 ALL PASSED (34/34) — {_id} hoàn thành — {n} câu hỏi ({labels})
GATE 4→5 PASSED — bài này hoàn tất, sang bài tiếp.

→ Chuyển sang bài tiếp theo (quay lại GATE 0→1 nếu là bài đầu batch, hoặc BƯỚC 1 nếu cùng batch).

BƯỚC CUỐI: VERIFY BATCH (sau khi gen xong TẤT CẢ bài)

Sau khi hoàn thành toàn bộ batch, chạy verify toàn bộ:

# 1. Validate tất cả file HTML (char count + broken ruby)
python3 .claude/skills/jlpt-reading-medium-passage/scripts/process_html.py \
  --validate --html-dir assets/html/doan_van_vua

# 1b. Auto-check furigana coverage cho TẤT CẢ file HTML
python3 .claude/skills/jlpt-reading-medium-passage/scripts/check_furigana.py \
  --html-dir assets/html/doan_van_vua \
  --csv rules/kanji_jlpt_sensei.csv

# 1c. Auto-check required CSV fields cho TẤT CẢ rows
python3 .claude/skills/jlpt-reading-medium-passage/scripts/check_csv_fields.py \
  --csv sheets/samples_v1.csv \
  --kind medium

# 1e. Auto-check dấu `。` cuối lựa chọn cho TẤT CẢ rows
python3 .claude/skills/jlpt-reading-medium-passage/scripts/check_answer_punctuation.py \
  --csv sheets/samples_v1.csv

# 1d. Auto-check わかち書き spacing cho TẤT CẢ file HTML
python3 .claude/skills/jlpt-reading-medium-passage/scripts/check_spacing.py \
  --html-dir assets/html/doan_van_vua

# 2. Đếm số rows trong CSV + check số câu hỏi
python3 -c "
import csv
expected_q = {'N1': 2, 'N2': 2, 'N3': 3, 'N4': 3, 'N5': 2}
with open('sheets/samples_v1.csv', 'r', encoding='utf-8') as f:
    rows = list(csv.DictReader(f))
print(f'Total rows: {len(rows)}')
bad = 0
for r in rows:
    lv = r.get('level')
    want = expected_q.get(lv, 0)
    got = sum(1 for i in range(1, 6) if r.get(f'question_{i}', '').strip())
    if got != want:
        bad += 1
        print(f\"  ❌ {r['_id']} ({lv}): {got} câu, expected {want}\")
print(f'Multi-question OK: {len(rows) - bad}/{len(rows)}')
for level in ['N1','N2','N3','N4','N5']:
    n = sum(1 for r in rows if r.get('level') == level)
    print(f'  {level}: {n}')
"

Batch-level checklist

• Mỗi bài có _id unique, đúng format {LEVEL}_{uuid}
• kind = đoạn văn vừa trong tất cả rows
• general_image = "" (empty) — KHÔNG có PNG
• general_audio = "" (empty)
• Char count trong Target Range cho mọi bài
• Không bài nào dưới Hard Reject threshold
• Furigana chỉ cho từ vượt level, không dạng "Ab", mọi <ruby> có <rt>
• Ruby tags count ≤ expected per level
• Mỗi bài có đúng số câu hỏi theo level (N1/N2/N5=2, N3/N4=3) — các slot khác empty
• question_label_i có question_ prefix (7 labels hợp lệ)
• Trong 1 bài có ≥ 2 label khác nhau (ngoại lệ N5)
• Mỗi câu hỏi có 4 đáp án ngăn cách \n (KHÔNG số thứ tự)
• correct_answer_i phân bố đều 1-4 trong batch
• Distractor dùng info từ bài (không bịa), ≥ 3 loại bẫy khác nhau per câu
• explain_vn_i + explain_en_i đủ 3 phần cho mọi câu
• Marker trong text khớp câu hỏi (① ↔ Q1 reference, [ ① ] ↔ Q fill_blank...)
• Multi-question coverage: Q1/Q2/Q3 test các đoạn/ý khác nhau trong từng bài
• text_read clean — không attribute, không class, không <rt> content
• <p> thuần, không <br> giữa câu (trừ N5 letter/diary)
• Annotation (注) giải thích bằng tiếng Nhật đơn giản, KHÔNG tiếng Anh/Việt
• Trong batch, tag đa dạng ≥ 3 category (nếu batch > 5)

Reference Data & Samples

Data mẫu có sẵn trong data/:

Load bằng:

# Stats tất cả levels
python3 .claude/skills/jlpt-reading-medium-passage/scripts/load_references.py --stats

# 3 random samples N3
python3 .claude/skills/jlpt-reading-medium-passage/scripts/load_references.py --level N3 --count 3

LƯU Ý khi đọc data gốc:

• Data gốc DÙNG <br> nhiều — thói quen xấu. Output HTML skill KHÔNG theo.
• Data gốc có <span> bọc paragraph — output KHÔNG cần.
• Data gốc N1 thường có 3 câu hỏi — skill follow spec EXPECTED_Q_COUNT (N1=2), không bắt chước data.
• Data gốc dùng ruby không đều (N4 thường rắc ruby thừa) — output follow rules/kanji_jlpt_sensei.csv.

Chi tiết phân tích từng level xem references/sample-analysis.md.

Common errors (dạng đoạn văn vừa hay gặp)

1. Chỉ gen 1 câu hỏi — SAI, đoạn văn vừa bắt buộc 2-3 câu theo level
2. Gen thừa (4-5 câu) cho N1 vì bắt chước data — SAI, N1 spec chỉ 2 câu
3. Tất cả câu dùng cùng 1 label — SAI, cần ≥ 2 labels khác nhau
4. 2 câu cùng hỏi 1 đoạn — SAI, coverage rule yêu cầu đoạn khác nhau
5. Marker ① trong bài nhưng không có câu hỏi reference — marker vô nghĩa
6. Câu hỏi hỏi ① nhưng HTML không có marker — câu hỏi không thể trả lời
7. N4/N5 có source line — 0% data thực tế, không phù hợp level
8. Distractor quá dễ — đoạn văn vừa đòi hỏi distractor dùng ≥ 3 loại bẫy đa dạng
9. Quên question_ prefix trong label — label phải là question_content_match, không phải content_match

Cảnh báo bảo mật dữ liệu

🚫 KHÔNG ĐƯỢC GHI VÀO THƯ MỤC rules/ — rules/question_sheet.csv, rules/topic.json, rules/kanji_jlpt_sensei.csv, rules/question_format.json, rules/mission.json, rules/rule_doc_hieu.md là file tham chiếu, chỉ đọc. Mọi dữ liệu gen phải ghi vào sheets/samples_v1.csv.