jlpt-doan-van-ngan

name: jlpt-doan-van-ngan description: > Generate JLPT "đoạn văn ngắn" (short-passage / 短文読解) reading comprehension passages as styled HTML files and output CSV training data for AI fine-tuning. Each passage is a short Japanese prose text (80–290 characters depending on level) testing content understanding via a single multiple-choice question. 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 ngắn" (短文読解). Use this skill whenever the user wants to: gen bài đoạn văn ngắn, tạo nội dung đoạn văn ngắn, generate short-passage reading comprehension, create JLPT 短文 passages, produce AI fine-tuning data for the đoạn văn ngắn 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 ngắn, tạo short passage, generate JLPT 短文, short reading passage N1/N2/N3/N4/N5.

JLPT 短文 / Đoạn Văn Ngắn — 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.
5. KHÔNG có screenshot — đoạn văn ngắn không cần PNG

Cấu trúc file

Outputs Per Passage

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

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

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 ngắn (短文):
   • 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
   • 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) — yêu cầu chất lượng từng loại
   • Phần 5 (7 loại bẫy = 5 chuẩn + Single-side + Peripheral Source)
   • Phần 6.1 (N5 短文), Phần 7.1 (N4 短文), Phần 8.1 (N3 短文), Phần 9.1 (N2 短文), Phần 10.1 (N1 短文) — tiêu chí chi tiết 4 chiều (chủ đề/hình thức/ngôn ngữ/Q&A) 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_ngan_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-short-passage/scripts/load_references.py --level N3 --count 3
   

6. Lập kế hoạch batch: mỗi bài gán format + topic + question_label khác nhau. 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, 6.1–10.1, 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-3 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Â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/news brief/letter/diary. Scan sheets/ + data/ để chọn format chưa/ít dùng.
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 question_label từ R5 — 7 labels, tuân theo distribution per level
5. Gen HTML theo rules → save assets/html/doan_van_ngan/{LEVEL}_{uuid}.html
   • Container max-width: 640px; 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)
   • Marker khớp với question_label (nếu reference/fill_in_blank)
   • Furigana chỉ cho từ vượt level (tra rules/kanji_jlpt_sensei.csv)
6. Gen câu hỏi + 4 đáp án theo rules/questions.md
   • 4 options ngăn cách \n, KHÔNG số thứ tự
   • correct_answer_1 = integer 1-4
   • Distractor phải có căn cứ trong bài (không bịa)
7. [BẮT BUỘC] Auto-check furigana ngay sau khi save HTML — chạy:

   python3 .claude/skills/jlpt-reading-short-passage/scripts/check_furigana.py \
     --file assets/html/doan_van_ngan/{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 (⚠️ dùng script, KHÔNG sửa CSV tay):

   python3 .claude/skills/jlpt-reading-short-passage/scripts/process_html.py \
     --file assets/html/doan_van_ngan/{LEVEL}_{uuid}.html \
     --csv sheets/samples_v1.csv \
     --tag "{topic_english}" \
     --question-label {question_label} \
     --question "Câu hỏi..." \
     --answers "Option1|Option2|Option3|Option4" \
     --correct 2 \
     --explain-vn "Giải thích VN 3 phần..." \
     --explain-en "Explanation EN 3 phần..."
   

   Hoặc điền Q&A sau khi row đã tồn tại bằng fill_qa.py (an toàn với commas):

   ⛔ KHÔNG ĐƯỢC sửa CSV bằng tay. Commas trong nội dung (ví dụ 100,000円, それは、...) sẽ làm vỡ cột. LUÔN dùng script — tự quote đúng.

   python3 .claude/skills/jlpt-reading-short-passage/scripts/fill_qa.py \
     --csv sheets/samples_v1.csv --row-id {LEVEL}_{uuid} \
     --question-label {question_label} \
     --q1 "Câu hỏi..." \
     --a1 "Đáp án 1
   Đáp án 2
   Đáp án 3
   Đáp án 4" \
     --ca1 2 \
     --evn1 "..." \
     --een1 "..."
   

🔒 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_ngan/{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)
• Q1 + 4 đáp án + correct_answer_1 + explain_vn_1 + explain_en_1 đều đã 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 short 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 + 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: {LEVEL}  |  Label: {question_label}
────────────────────────────────
[ 1] ✅ PASS — Char count (235 chars, range 220-290)
[ 2] ❌ FAIL — Flow text (found 2x 。<br>)
[ 3] ✅ PASS — Container CSS (640px, 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.

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

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

• TÔI SẼ kiểm tra ĐẦY ĐỦ 26 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á 26 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: 30 checks (26 manual + 4 auto-script) ở 3 phần (A HTML, B content, C questions + C2 verify). KHÔNG có PHẦN D ảnh vì không có screenshot.

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)

Agent đọc nội dung bài viết và đánh giá:

PHẦN C: CÂU HỎI & ĐÁP ÁN (8 checks)

Agent đọc câu hỏi + 4 đáp án từ CSV và đánh giá:

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

Agent tự giải bài 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.

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

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

• Đã hoàn tất đánh giá ĐẦY ĐỦ 26/26 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-short-passage/scripts/process_html.py --refresh --html-dir assets/html/doan_van_ngan --csv sheets/samples_v1.csv
3. Verify: python3 .claude/skills/jlpt-reading-short-passage/scripts/process_html.py --validate --html-dir assets/html/doan_van_ngan --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-short-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-short-passage/scripts/process_html.py \
  --refresh \
  --file assets/html/doan_van_ngan/{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Ả 26 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 26 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 30 mục TRỌN VẸN (gồm 4 auto-script + 26 manual) ở vòng cuối (không skip)
• TẤT CẢ 30/30 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 (mục #25) thực sự thực hiện: agent tự giải bài + chọn đáp án mà không nhìn correct_answer_1 → 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Ả 29 checks PASS + GATE 4→5 PASSED → log:

🎉 ALL PASSED (30/30) — {_id} hoàn thành
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-short-passage/scripts/process_html.py \
  --validate --html-dir assets/html/doan_van_ngan

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

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

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

# 2. Đếm số rows trong CSV = đúng số bài đã gen
python3 -c "
import csv
with open('sheets/samples_v1.csv', 'r', encoding='utf-8') as f:
    rows = list(csv.DictReader(f))
print(f'Total rows: {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}')
"

# 3. (Optional) Merge multi-level CSV nếu có nhiều file
# (hầu hết use case chỉ có 1 file samples_v1.csv)

Batch-level checklist

• Mỗi bài có _id unique, đúng format {LEVEL}_{uuid}
• kind = đoạn văn ngắn 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 (hoặc đã gen lạ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 (N5: 2, N4: 4, N3: 6, N2: 4, N1: 2)
• Mỗi bài có đúng 1 câu hỏi (question_2 → question_5 empty)
• question_label_1 đa dạng (≥ 2 label khác nhau nếu batch > 3 bài; ≥ 3 nếu batch > 5)
• Mỗi câu hỏi có 4 đáp án ngăn cách \n trong answer_1 (KHÔNG số thứ tự)
• correct_answer_1 phân bố đều 1-4 trong batch (không lặp ≥ 3 bài liên tiếp)
• Distractor dùng info từ bài (không bịa)
• explain_vn_1 + explain_en_1 đủ 3 phần
• Marker trong text khớp câu hỏi (nếu có <u>, [ ① ], ...)
• 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)
• 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-short-passage/scripts/load_references.py --stats

# 3 random samples N3
python3 .claude/skills/jlpt-reading-short-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 N4 rắc ruby trên từ đúng level — output KHÔNG theo.

Đọc sample để học nội dung/chủ đề/question pattern, KHÔNG bắt chước styling xấu của data gốc.

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

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/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.