example-sentences

name	example-sentences
description	Requirements for creating and revising example sentences in je-dict-1. Covers minimum counts, progressive length, vocabulary restrictions by tier, and quality standards.

Example Sentence Guidelines

This skill defines the standards for example sentences across all dictionary entries. All entry-creation and revision activities must follow these guidelines.

---

Minimum Example Counts by Tier

Basic and Core Tiers

Every sense of every entry in the basic and core tiers must have at least 5 example sentences.

Tier	Minimum Examples per Sense
Basic	5
Core	5

General Tier

Every sense of every entry in the general tier must have at least 3 example sentences.

Tier	Minimum Examples per Sense
General	3

Multi-sense entries: The requirements apply per sense. An entry with 3 senses in the basic tier needs at least 15 examples total (5 per sense).

Minimums are sufficient. Exceeding the minimum by 0–1 examples per sense is fine when a useful additional collocation comes to mind, but routinely producing 5 examples for a single general-tier sense (when 3 are required) inflates the entry without adding value. Match the example count to the entry's complexity; don't pad.

---

Progressive Length Requirement

Examples within each sense should progress from shorter to longer:

1. Example 1: Short and simple - demonstrates the word clearly
2. Example 2: Slightly longer - shows basic context
3. Example 3: Medium length - natural usage with fuller context
4. Example 4 (basic/core): Longer sentence with more complex structure
5. Example 5 (basic/core): Longest - may consist of 2-3 short sentences or one longer sentence with relative clauses, compound structures, etc.

Key principle: Early examples help learners recognize the word; later examples show how the word functions in natural, flowing Japanese.

Length Guidelines

Example	Target Length (Japanese)
1	5-15 characters
2	10-20 characters
3	15-30 characters
4	25-45 characters
5+	35-70 characters (or 2-3 short sentences)

These are guidelines, not strict rules. Natural expression takes priority over hitting exact character counts.

---

Vocabulary Restrictions by Tier

Basic Tier Entries

For entries in the basic vocabulary tier:

Examples	Vocabulary Restriction
1-2	Basic tier only - Use only words from the basic tier
3-5	Basic + Core tiers - May use basic and core vocabulary

Critical: Basic tier examples must contain no general-tier or unlisted vocabulary. This ensures learners at the basic level can fully understand all examples without encountering unknown words.

Core Tier Entries

For entries in the core vocabulary tier:

Examples	Vocabulary Restriction
1-2	Basic + Core tiers - Use only basic or core vocabulary
3-5	No restriction - May use any vocabulary

Recommendation: Even for unrestricted examples (3-5), avoid vocabulary that is not in the dictionary. Learners should be able to look up any unfamiliar word.

General Tier Entries

For entries in the general vocabulary tier:

Examples	Vocabulary Restriction
1-3+	No restriction - May use any vocabulary

Recommendation: Avoid obscure vocabulary not in the dictionary. Use common, natural expressions that learners are likely to encounter.

---

Vocabulary Tier Verification

When creating examples for basic and core tier entries, verify vocabulary tier compliance:

# Check if a word is in the dictionary and its tier
python3 build/check_duplicate.py "word" "reading"

For systematic verification during polishing:

• Read the example sentence
• Identify all content words (nouns, verbs, adjectives, adverbs)
• Verify each word is in the appropriate tier
• Replace non-compliant words with tier-appropriate alternatives

Common substitution patterns:

Non-compliant	Basic alternative	Core alternative
{購入	こうにゅう}する	{買
{使用	しよう}する	{使
{非常	ひじょう}に	とても
{困難	こんなん}	{難

---

Sense Numbers Requirement

Every example must include a sense_numbers field linking it to the definition(s) it illustrates.

"examples": [
  {
    "id": "00001_word_ex1",
    "japanese": "...",
    "english": "...",
    "sense_numbers": [1],
    "has_audio": false,
    "notes": null
  }
]

Rules

• Single-sense entries: Use [1] for all examples
• Multi-sense entries: Each example must specify which sense(s) it demonstrates
• Examples illustrating multiple senses: Use [1, 2] format
• Must reference valid senses: Numbers must match sense_number values in definitions

Distribution for Multi-Sense Entries

For entries with multiple senses in basic/core tiers:

• Each sense needs at least 5 examples
• Distribute examples to cover all senses adequately
• Some examples may illustrate multiple senses (use [1, 2] notation)

---

Quality Standards

Essential Requirements

1. Natural Japanese: Examples should sound like something a native speaker would say
2. Clear context: The usage should be understandable from the example
3. Complete furigana: All kanji must have {kanji|reading} markup
4. Accurate translation: English captures meaning without being overly literal

Content Quality

1. First example should be simple - Demonstrate the word clearly without complexity
2. Progress to natural complexity - Later examples show real-world usage
3. Include fixed phrases - High-frequency collocations aid memory (at least one per sense)
4. Show grammatical connections - Demonstrate how words connect with particles, etc.
5. Annotate non-obvious grammar - Use notes field for explanations when needed

What to Demonstrate

Examples should illustrate:

• Common collocations and set phrases
• Typical particle patterns (for verbs)
• Predicate vs. modifier usage (for adjectives)
• Register-appropriate contexts
• Both literal and figurative meanings (if applicable)

---

Example Format Reference

{
  "id": "00396_taberu_ex1",
  "japanese": "{朝|あさ}ごはんを{食|た}べる。",
  "english": "To eat breakfast.",
  "sense_numbers": [1],
  "has_audio": false,
  "notes": null
}

ID Format

Pattern: {entry_id}_ex{N}

• entry_id: The entry's ID (e.g., 00396_taberu)
• N: Sequential number starting from 1

Fields

Field	Required	Description
id	Yes	Unique example ID
japanese	Yes	Japanese sentence with furigana
english	Yes	Natural English translation
sense_numbers	Yes	Array of sense numbers illustrated
has_audio	Yes	Boolean (usually false)
notes	Yes	Explanatory note or null

---

Common Issues to Avoid

1. Adding inline links: Do NOT add inline word links (⟦...⟧) when creating or revising examples. Links are added in a separate polishing step via prompts/polish_add_inline_links.md.
2. Missing furigana: お金が余った instead of お{金|かね}が{余|あま}った
3. Overly literal translations: "As for me, I eat sushi" instead of "I eat sushi"
4. Wrong sense_numbers: Example linked to wrong definition
5. Unnatural constructions: Grammatically correct but rarely used patterns
6. Vocabulary tier violations: Using general-tier words in basic-tier examples 1-2
7. Insufficient examples: Not meeting minimum counts per sense
8. No length progression: All examples being similar length

---

Polishing Checklist for Examples

When reviewing or revising examples, verify:

Count and Distribution

• Minimum examples per sense met (5 for basic/core, 3 for general)
• All senses have adequate example coverage
• Examples are properly distributed across senses

Progressive Length

• Examples progress from shorter to longer within each sense
• Final examples are substantially longer or multi-sentence

Vocabulary Restrictions

• Basic tier: Examples 1-2 use only basic vocabulary
• Basic tier: Examples 3-5 use only basic+core vocabulary
• Core tier: Examples 1-2 use only basic+core vocabulary
• No unlisted vocabulary in restricted examples

Quality

• All examples sound natural
• All kanji have complete furigana
• Translations are accurate and natural
• sense_numbers are correct for each example
• At least one example shows a common collocation
• Grammar patterns are demonstrated clearly

Format

• IDs follow {entry_id}_ex{N} pattern
• IDs are sequential (ex1, ex2, ex3...)
• All required fields present
• has_audio is accurate
• notes field present (null if not needed)

---

Adding Examples to Existing Entries

When adding examples to bring an entry into compliance:

1. Read the existing entry to understand current examples
2. Identify gaps: Which senses need more examples? What lengths are missing?
3. Check vocabulary tier: Determine what vocabulary can be used
4. Write new examples following progressive length guidelines
5. Verify compliance with all requirements
6. Update modified timestamp in metadata

Example Addition Template

For a basic-tier entry with one sense needing 5 examples:

Example 1: [short, basic vocab only]
Example 2: [short-medium, basic vocab only]
Example 3: [medium, basic+core vocab]
Example 4: [medium-long, basic+core vocab]
Example 5: [long or multi-sentence, basic+core vocab]

---

Summary Table

Tier	Min Examples/Sense	Ex 1-2 Vocab	Ex 3+ Vocab
Basic	5	Basic only	Basic + Core
Core	5	Basic + Core	Any (prefer dictionary words)
General	3	Any	Any (prefer dictionary words)