yorisoi

yorisoi — Easy Japanese conversion skill

1. Declaration of intent

"Easy Japanese" is Japanese adjusted so that it is understood by readers unfamiliar with Japanese (foreign residents and Japanese-language learners). This skill rewrites in compliance with the public external standard guideline (Immigration Services Agency of Japan and Agency for Cultural Affairs, "Guidelines for Easy Japanese for Residency Support", August 2020).

The difference from meiseki (clarification) lies in the target reader. meiseki lowers the reading burden for native Japanese readers. yorisoi reduces the text to vocabulary and syntax that readers at the target vocabulary level (by default equivalent to N4) can understand. Both adopt a two-layer structure: "detection and scoring in the deterministic layer, rewriting in the LLM layer".

2. Operation modes and output policy

• Conversion mode (default): rewrite into Easy Japanese and returnonly the body text. Do not attach analysis or commentary.
• Judgment mode: if "check only", "judgment only", or "score only" is specified, without rewriting, report violations and vocabulary-level exceedances with line positions, and show the YLS (§7).
• The target level is N4 by default. Change it if specified, such as "at N3" or "at N5 level".
• Only when "tell me what you changed" is explicitly stated, add the changes after the body text.

3. In scope / out of scope

• In scope: explanatory texts that you want readers unfamiliar with Japanese to read as well, such as notices, guidance, explanations of administrative procedures, disaster prevention information, manuals, and internal announcements.
• Out of scope: code itself, the text of laws and contracts themselves, strict medical descriptions, and creative writing. For documents requiring legal effect or strictness, present the Easy Japanese version alongside as a "reference translation" and keep the original text.
• Mixed documents: rewrite only the body text and leave code blocks, quotations, URLs, and contact information as in the original.
• Adding furigana or word separation is out of scope (as of v0.6.0).

4. Workflow (perform in this order)

Step 1. Read the whole text and grasp the meaning and the reader's actions

Determine what the reader of this document should know and what they should do. If conditions, exceptions, deadlines, or contact information are dropped as a result of making it easy, that is a failure.

Step 2. Run textlint (deterministic layer)

Write the manuscript to a temporary file (extension .md), andnpx run textlint via and read the JSON.

npx --min-release-age=7 --yes --package textlint@14.8.4 --package textlint-rule-preset-ja-technical-writing@10.0.2 --package textlint-rule-prh@6.1.0 textlint -c "<SKILL_DIR>/references/textlint-yorisoi.config.json" -f json "<INPUT_MD>"

• <SKILL_DIR> is this SKILL.md replace with the actual path of the directory containing it.
• If there is a finding, the exit code becomes 1, but read the JSON on stdout and continue processing.

Step 3. Determine vocabulary level (deterministic layer)

Use the bundled script to identify words that exceed the target level.

node "<SKILL_DIR>/scripts/vocab-check.js" --level N4 --format json "<INPUT_MD>"

• --level is the target level (N5–N1). The first run takes several tens of seconds to fetch the morphological analyzer (cached thereafter).
• Output over(exceeded) are rewrite candidates,unknown(out of list) is for reference.Judgment is an estimate, and final judgment is made based on context (seereferences/vocab/README.md ).

Step 4. Calculate YLS(before)

Compute the before score using the formula in §7. In judgment mode, report here and finish.

Step 5. Rewrite according to YA→YH in patterns-yorisoi.md

references/patterns-yorisoi.md and fix in the order ofpriority YA→YH.

• YB (double negation) is collapsed without inverting its truth value (same criterion as A in meiseki).
• prh findings (YC passive, YD conjecture, YE honorific, YG notation) are the starting point for rewriting. Because detection is approximate, false positives (such as the potential form "される") may be ignored.
• For words that exceed the vocabulary level, either paraphrase them or attach an explanation in the form "余震＜＝後から来る地震＞". Explanations must be derived only from the original text and context. Do not invent new information.

Step 6. Verify meaning (the most important guard)

• For places where double negation was collapsed, check that the direction of the logic matches the original text.
• Check that conditions, exceptions, deadlines, numerical values, and contact information all match the original text.
• Check that the explanation in "＜＝explanation＞" does not diverge from the meaning of the original text.

Step 7. Re-run textlint and vocab-check, and verify before→after

• after < before（YLS） If it is not, there are remaining fixes.
• Double negation: 0 instances、Aim for 0 vocabulary exceedances(proper nouns and important words left with explanations are not counted as exceedances).

Step 8. Return only the body text

As per the policy in §2, in conversion mode output only the rewritten body text.

5. Guardrails (things you must not do)

• Do not change meaning, facts, numerical values, deadlines, or contact information. Do not remove information in order to make it easier.
• Do not add new information. "＜＝explanation＞" must also be derived only from the original text and context.
• Do not change proper nouns (place names, organization names, personal names, system names). For system names that are difficult to read, attach an explanation.
• Use "です・ます" consistently at sentence endings. Do not drop to casual plain style.
• Do not remove "〜かもしれません" (this is the result of changing conjecture from a vague expression to a clear form).
• Strict sentences in laws, contracts, and medicine are out of scope for rewriting. If requested, explicitly state their position as a "reference translation".
• If the original document is already easy, do not touch it.

6. Final judgment criteria

Can a reader who has only vocabulary at the target level, after reading once, correctly understand "what should be done"?

7. Definition of the Yasaness Load Score (YLS)

Weight the findings from textlint and vocab-check by category, and normalize by the number of sentences in the body text.The lower, the easier.

YLS = Σ(カテゴリ件数 × 重み) ÷ 本文の文数 × 100

Category	Detection	Weight
YB Double negation	no-double-negative-ja + prh A1	3
YF Vocabulary overage	vocab-check の over（unknown are not counted)	2
YA Sentence length/commas	sentence-length, max-ten, no-doubled-conjunctive-particle-ga	2
YF Kanji runs/verbosity	max-kanji-continuous-len, ja-no-redundant-expression	2
YC/YD/YE/YG	prh (other than A1), no-mix-dearu-desumasu	1
Other	no-doubled-joshi, no-doubled-conjunction	1

• prh A1 (completion of double negation) is counted in YB and is not double-counted with YC–YG.
• Acceptance criteria: after < before required、Double negation 0 cases、Aim for 0 vocabulary overages。
• As reference values, the jReadability approximation output by vocab-check (the higher, the easier) may also be noted. The approximation is not used for judgment.

8. Division of labor for machine detection (what can be caught / what cannot)

• What textlint catches: Double negation (separated type and polite form are prh A1), sentence length, excessive commas, kanji runs, verbose expressions, mixed sentence endings, typical forms of passive/conjecture/honorifics/notation (prh YC–YG. Approximate).
• What vocab-check catches: Words exceeding the target level (the bundled estimated list. If JEV is available, it takes top priority).
• What the LLM judges: Sorting false positives for passive, differentiating paraphrases and the use of "<= explanation >", the degree of establishment of loanwords, leading with important information (YH), sentence split positions, avoiding romanization.

This division of labor follows the same design philosophy as meiseki (detection is the deterministic layer, rewriting is the LLM layer).