jlpt-doan-van-dai

name: jlpt-doan-van-dai description: > Generate JLPT "đoạn văn dài" (long-passage / 長文読解) reading comprehension passages as styled HTML files and output CSV training data for AI fine-tuning. Each passage is a long Japanese prose text (550–1150 characters depending on level) testing deep comprehension of outline, logical development, author's ideas, and reference phrases via 3-4 multiple-choice questions per passage. CHỈ áp dụng N1 (3 câu, ~1000 chars) và N3 (4 câu, ~550 chars) — N2/N4/N5 KHÔNG có dạng này. 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 dài" (長文読解). Use this skill whenever the user wants to: gen bài đoạn văn dài, tạo nội dung đoạn văn dài, generate long-passage reading comprehension, create JLPT 長文 passages, produce AI fine-tuning data for the đoạn văn dài section of JLPT N1/N3, 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 dài, tạo long passage, generate JLPT 長文読解, long reading passage N1 / N3.

JLPT 長文 / Đoạn Văn Dài — 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_dai/{LEVEL}_{uuid}.html
2. Clean HTML → CSV column text_read (no attributes, no <rt> content)
3. CSV row → sheets/samples_v1.csv với 3-4 câu hỏi populate (slot còn lại empty)

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

Scope — CHỈ N1 và N3

⛔ KHÔNG gen N2, N4, N5 cho dạng đoạn văn dài — sẽ bị reject bởi spec.

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

⛔ COVERAGE RULE: 3-4 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, lý tưởng ≥ 3. ⛔ CÂU CUỐI RULE: N1 câu 3 = question_author_opinion. N3 câu 4 = question_content_match hoặc question_author_opinion (test tổng thể).

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 khi 注 dài), tiêu chí chi tiết per level). Phần áp dụng trực tiếp cho dạng đoạn văn dài (長文) — CHỈ N1 và N3:
   • Phần 1 (Tổng quan & Nguyên tắc 程度) — biên ± per level; 書き下ろし bắt buộc N3, có thể trích nguồn N1
   • Phần 2 (Hình thức) — ①②③ thường có; 注 bắt buộc khi có thuật ngữ
   • Phần 2.4 (Thể chia nhất quán 文体の統一) — N1/N3 dùng 普通形 (だ・である); văn bản + câu hỏi + 4 đáp án phải thống nhất thể chia (long-passage chỉ N1/N3 → toàn bộ 普通形).
   • 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 reference (×1-2), reason_explanation, author_opinion (N1), content_match/meaning_interpretation
   • Phần 5 (7 loại bẫy = 5 chuẩn + Single-side + Peripheral Source)
   • Phần 8.3 (N3 長文 ~550字, 4 câu), Phần 10.3 (N1 長文 ~1000字, 3 câu) — tiêu chí chi tiết 4 chiều
   • 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_dai_n{1,3}_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-long-passage/scripts/load_references.py --level N1 --count 2
   python3 .claude/skills/jlpt-reading-long-passage/scripts/load_references.py --level N3 --count 2
   

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 ≥ 2 category trong batch > 3 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 + 4 marker strategy patterns

1. Gen _id = {LEVEL}_{uuid.uuid4().hex} (full 32-char hex). Level ∈ {N1, N3}.
2. Chọn format từ R7 (rules/content.md) — 5 formats: essay/tiểu luận (N1), bài báo/thư dài/anecdote (N3).
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 (3 câu): Combo 1 reference(①) + reason + author_opinion (phổ biến nhất)
   • N1 khác: Combo 2 meaning + reason + author_opinion | Combo 3 reference(①) + reference(②) + author_opinion
   • N3 (4 câu): Combo 1 reference(①) + reference(②) + reason + content_match (phổ biến nhất)
   • N3 khác: Combo 2/3/4 — xem rules/questions.md R5
   • Câu cuối: N1 = author_opinion; N3 = content_match/author_opinion
5. Gen HTML theo rules → save assets/html/doan_van_dai/{LEVEL}_{uuid}.html
   • Container max-width: 780px; margin: 0 auto; padding: 56px 64px; line-height: 1.95
   • 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 (đoạn văn dài KHÔNG có exception)
   • Paragraph count: N1 = 5-8, N3 = 4-6
   • Marker ①②③ khớp với các câu hỏi question_reference
   • Furigana chỉ cho từ vượt level (tra rules/kanji_jlpt_sensei.csv) — data 0% nên giữ ít
   • Source line: N1 rất nên có (data 70%), N3 optional (data 38%)
   • Annotation 注: N3 rất nên có (data 64%, 2-3 cái), N1 optional (25%, 1-2 cái)
6. Gen 3-4 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)
   • Paraphrase: đáp án đúng KHÔNG copy > 4 từ (N1) hoặc > 5 từ (N3) liên tiếp
   • 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-long-passage/scripts/check_furigana.py \
     --file assets/html/doan_van_dai/{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 3-4 câu: JSON
   python3 .claude/skills/jlpt-reading-long-passage/scripts/process_html.py \
     --file assets/html/doan_van_dai/{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.

   # Ví dụ N1 (3 câu)
   python3 .claude/skills/jlpt-reading-long-passage/scripts/fill_qa.py \
     --csv sheets/samples_v1.csv --row-id {LEVEL}_{uuid} --level N1 \
     --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_author_opinion --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_dai/{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 long 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: N1  |  Q count: 3/3  |  Labels: [reference, reason, author_opinion]
────────────────────────────────
[ 1] ✅ PASS — Char count (1087 chars, range 1000-1150)
[ 2] ❌ FAIL — Flow text (found 2x 。<br>)
[ 3] ✅ PASS — Container CSS (780px, 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á 32 mục checklist), agent PHẢI cam kết:

• TÔI SẼ kiểm tra ĐẦY ĐỦ 32 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á 32 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: 36 checks (32 manual + 4 auto-script) ở 4 phần (A HTML 11, B content 6, C questions/answers + C2 verify 12, D multi-question coverage 3).

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 (11 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 (11 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..Q4):

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 quan trọng cho đoạn văn dài: 3-4 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á 32 mục, agent PHẢI confirm trước khi vào fix loop:

• Đã hoàn tất đánh giá ĐẦY ĐỦ 32/32 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-long-passage/scripts/process_html.py --refresh --html-dir assets/html/doan_van_dai --csv sheets/samples_v1.csv
3. Verify: python3 .claude/skills/jlpt-reading-long-passage/scripts/process_html.py --validate --html-dir assets/html/doan_van_dai --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-long-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-long-passage/scripts/process_html.py \
  --refresh \
  --file assets/html/doan_van_dai/{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Ả 32 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 32 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 36 mục TRỌN VẸN (gồm 4 auto-script + 32 manual) ở vòng cuối (không skip)
• TẤT CẢ 36/36 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Ả 35 checks PASS + GATE 4→5 PASSED → log:

🎉 ALL PASSED (36/36) — {_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).

Batch size: 3-5 bài/lần (bài dài + nhiều câu hỏi, workload cao nhất trong series).

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-long-passage/scripts/process_html.py \
  --validate --html-dir assets/html/doan_van_dai

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

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

# 1e. Auto-check dấu `。` cuối lựa chọn cho TẤT CẢ rows
python3 .claude/skills/jlpt-reading-long-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-long-passage/scripts/check_spacing.py \
  --html-dir assets/html/doan_van_dai

# 2. Đếm số rows trong CSV + check số câu hỏi + last-label rule
python3 -c "
import csv
expected_q = {'N1': 3, 'N3': 4}
last_rules = {'N1': ['question_author_opinion'],
              'N3': ['question_content_match', 'question_author_opinion']}
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')
    if lv not in expected_q:
        continue
    want = expected_q[lv]
    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}\")
        continue
    last_lbl = r.get(f'question_label_{want}', '')
    if last_lbl not in last_rules[lv]:
        bad += 1
        print(f\"  ❌ {r['_id']} ({lv}): câu cuối = {last_lbl}, expected {last_rules[lv]}\")
print(f'Multi-question OK: {len(rows) - bad}/{len(rows)}')
for level in ['N1','N3']:
    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}, Level ∈ {N1, N3}
• kind = đoạn văn dài trong tất cả rows
• level chỉ là N1 hoặc N3 (KHÔNG có N2/N4/N5)
• general_image = "" (empty) — KHÔNG có PNG
• general_audio = "" (empty)
• Char count trong Target Range (N1:1000-1150, N3:550-700)
• Không bài nào dưới Hard Reject threshold (N1:900, N3:500)
• Paragraph count N1:5-8, N3:4-6
• Furigana chỉ cho từ vượt level, không dạng "Ab", mọi <ruby> có <rt>
• Ruby tags count ≤ expected (N1:6, N3:15)
• Mỗi bài có đúng số câu hỏi theo level (N1=3, N3=4) — các slot khác empty
• N1 câu 3 = question_author_opinion. N3 câu 4 = question_content_match/question_author_opinion
• question_label_i có question_ prefix (7 labels hợp lệ)
• Trong 1 bài có ≥ 2 label khác nhau (lý tưởng ≥ 3)
• 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 (① ↔ Q reference)
• Multi-question coverage: 3-4 câu 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
• Annotation (注) giải thích bằng tiếng Nhật đơn giản, KHÔNG tiếng Anh/Việt
• Source line dùng tên tác giả tự chế (KHÔNG dùng tên tác giả thật)
• Trong batch, tag đa dạng ≥ 2 category (nếu batch > 3)

Reference Data & Samples

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

N2, N4, N5 KHÔNG CÓ file data cho đoạn văn dài — không applicable.

Load bằng:

# Stats N1/N3
python3 .claude/skills/jlpt-reading-long-passage/scripts/load_references.py --stats

# 2 random samples N1
python3 .claude/skills/jlpt-reading-long-passage/scripts/load_references.py --level N1 --count 2

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

• Data gốc DÙNG <br> nhiều (N1 29%, N3 52%) — 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ó 4 câu hỏi (74%) — skill follow spec EXPECTED_Q_COUNT (N1=3), không bắt chước data.
• Data gốc N3 thường có 4 câu (82%) — skill follow spec (N3=4) OK.
• Data gốc ruby = 0% — skill giữ ít ruby (0-3 cặp ưu tiên).

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

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

1. Gen level ngoài N1/N3 — SAI, skill này CHỈ N1/N3
2. N1 gen 4 câu (bắt chước data) — SAI, spec N1 = 3 câu
3. N1 câu cuối là reference/content_match — SAI, phải là question_author_opinion
4. N3 câu cuối là reference — SAI, phải là question_content_match hoặc question_author_opinion (tổng thể)
5. Bài chỉ 2-3 paragraph — SAI, N1 cần 5-8, N3 cần 4-6 paragraph
6. Tất cả câu dùng cùng 1 label — SAI, cần ≥ 2 labels khác nhau
7. 2-3 câu cùng hỏi 1 đoạn — SAI, coverage rule yêu cầu đoạn khác nhau
8. Marker ① trong bài nhưng không có câu hỏi reference — marker vô nghĩa
9. Câu hỏi hỏi ① nhưng HTML không có marker — câu hỏi không thể trả lời
10. Thiếu source line ở N1 — giảm authenticity (data 70%)
11. N3 không có annotation — giảm authenticity (data 64%)
12. Dùng <br> giữa câu — SAI, dùng <p> thuần
13. Ruby quá nhiều (> 6 cho N1, > 15 cho N3) — đoạn văn dài thực tế gần như không có ruby
14. Distractor yếu — đoạn văn dài đòi hỏi distractor sai ở 1 nuance (thời gian, nhân-quả đảo, phạm vi)
15. 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.