Ust Gen

When a context file is provided:

• Do not substitute published ULT from data/published_ult_english/
• Do not guess issue-file locations
• Do not fetch another ULT unless the context is missing the needed source

Important: T4T-Based Workflow

The UST creation process starts with the T4T (Translation for Translators) as the base text. The goal is to modify T4T as little as possible while ensuring it is:

1. True to the Hebrew (final authority on meaning)
2. Consistent with the ULT (same meaning, different form)
3. Compliant with unfoldingWord standards (style, vocabulary, formatting)

Do NOT start from scratch. Read the T4T first, verify it against Hebrew/ULT, then make targeted adjustments.

Note on published UST: The UST currently on Door43, if not from our recently published approved work, was adapted from T4T long ago by underskilled volunteers and should largely be ignored as a reference. Use T4T as your primary starting point.

Key Principle: Differentiate from ULT

The UST must be noticeably different from the ULT. If the only difference is removing "And" at the start, you haven't done enough.

The UST should:

• Use simpler, more common words than the ULT
• Explain meaning rather than preserve form

Test: Read the ULT and UST side by side. If they sound nearly identical, rewrite the UST. In particular, when the ULT preserves figurative imagery (metaphors, yoke/burden language, body-part idioms), the UST should unpack the meaning rather than echo the same image.

Simpler Vocabulary

Prefer common words over formal/literary ones:

Collapsing Parallelism

Hebrew poetry often says the same thing twice with different words (synonymous parallelism). In UST, collapse true parallelism into one statement when both lines express the same meaning.

Judgment call: If the second line adds new information or contrasts with the first, keep both lines. If it just restates the first line with different words, collapse them.

7-Step Workflow

Step 1: Read T4T Base

Use mcp__workspace-tools__read_usfm_chapter to read only the target chapter from the T4T file (e.g., file: data/t4t/25-LAM.usfm, chapter: 3). Do NOT read the entire book file — only the chapter you are generating.

Use mcp__workspace-tools__fetch_t4t when T4T files are missing or stale.

T4T uses special markers that serve two purposes:

1. Guide your UST rendering - they identify translation issues in the text
2. Must be removed - the markers themselves don't appear in final UST

These markers are valuable pre-identified translation issues - use them to inform your rendering choices before removing them from the final text. When you see [MET] or [SIM], the T4T is flagging figurative language — strip the marker AND replace the figure with what it means in plain English.

Step 2: Verify T4T's Meaning Accuracy Against Hebrew

Check that T4T accurately represents the Hebrew meaning:

1. Read Hebrew source — use mcp__workspace-tools__read_usfm_chapter on data/hebrew_bible/[BOOK].usfm for the target chapter only
2. Read corresponding ULT — if --context was provided, read sources.ult from context.json. Otherwise use mcp__workspace-tools__read_usfm_chapter on the freshest available local ULT, falling back to a fresh mcp__workspace-tools__fetch_door43 from en_ult
3. Note any discrepancies where T4T misunderstands Hebrew meaning

Key relationship:

• Hebrew = final authority on meaning
• ULT = what the Hebrew says (form)
• T4T/UST = what the Hebrew means (meaning)

If T4T diverges from Hebrew meaning, correct the meaning. If T4T and ULT express the same meaning differently, that's expected — they serve different purposes.

The purpose of this step is to catch T4T meaning errors — places where the T4T got the meaning wrong. It is NOT a license to import Hebrew phrasing, imagery, or structure into the UST. If the T4T's meaning is correct, keep the T4T's wording even if the Hebrew is more vivid or poetic.

Step 2.5: Check Identified Translation Issues

Before generating UST, check for any pre-identified translation issues:

1. If --context was provided and sources.issues is set, use that exact issues TSV path. Otherwise look for issue files at output/issues/<BOOK>/<BOOK>-<CHAPTER>.tsv and verse-range variants under output/issues/<BOOK>/

2. If found, read the identified issues - these flag constructions needing attention:

   • figs-activepassive: MUST convert to active voice in UST
   • figs-abstractnouns: Consider verbal/clausal forms
   • figs-nominaladj: Unpack nominalized adjectives
   • figs-metaphor/figs-simile: State the plain meaning in non-figurative language. Do not preserve the metaphorical image — if the Hebrew says "poured out his anger," write "showed how extremely angry he was," not "poured out his anger." If a simile is flagged, collapse it into a direct statement rather than keeping the comparison.
   • figs-personification: State the plain meaning; do not give the non-living thing an action verb
   • figs-idiom: Explain rather than preserve
   • figs-rquestion: Consider if rhetorical function is clear
   • figs-apostrophe: Convert direct address to third person ("this city" not "you, O city")

3. Use identified issues to guide your transformation decisions in Step 4

Step 3: Identify Changes Needed

Compare T4T to unfoldingWord standards. Flag areas that need adjustment:

1. Check Issues Resolved for authoritative decisions using Grep on data/issues_resolved_optimized.txt (topically organized). If that file is missing, fall back to data/issues_resolved.txt.

2. Remove T4T notation markers - [IDI], [DOU], [SYN], [RHQ], [EUP], [MTY], [MET], [SIM]

3. Handle \add...\add* markers - weave into prose; rarely bracket (see Step 4A)

4. Check for unfoldingWord-specific requirements:

   • Divine names: Must use "Yahweh" (not "the LORD")
   • Proper names: Same as ULT (no modern equivalents)
   • Active voice for psalm superscriptions
   • No initial conjunctions ("And", "But")

Step 4: Make Minimal Modifications

Apply only necessary changes. The T4T is already a good meaning-based translation.

A. Handle T4T Markers

T4T \add...\add* markers: These mark where T4T added clarifying information. In UST, most of this content should be woven into natural prose WITHOUT brackets. Only use {brackets} when the added content is:

1. Truly absent from the Hebrew (not just restructured)
2. Essential for comprehension (not just helpful)
3. Would seem "added" to a careful reader

Important edge case: If a \add phrase is a verse-initial framing clause (scene-setting such as travel/worship setting, speaker setup, or inferred self-talk context) and it has no direct Hebrew expression, prefer {brackets} instead of plain prose.

Example (PSA 121:1):

• Better: {As I travel toward Jerusalem,} I look toward the hills and ask myself, “Where will my help come from?”
• Worse: As I travel toward Jerusalem, I look toward the hills ... (reads as if directly expressed in source)

Quick decision check per \add segment: drop / weave / bracket.

• Drop if non-essential and redundant
• Weave if naturally implied and not likely perceived as added
• Bracket if it introduces explicit new framing that is not in the source text

See reference/ust_patterns.md Section 8 for detailed guidance.

B. Divine Names (if needed)

T4T may use "the LORD" or other renderings. Update to:

• יהוה = "Yahweh"
• אֲדֹנָי = "Lord"
• אֵל / אֱלֹהִים = "God"
• "angel of Yahweh" = "an angel representing Yahweh"
• יהוה צְבָאוֹת (Yahweh tsvaot) = "Yahweh, the commander of the heavenly armies" (not "Yahweh of Armies" -- that is the ULT rendering)

C. Check Vocabulary Against Issues Resolved

Use Grep for issues/glossary checks and mcp__workspace-tools__build_ust_index (lookup) for published precedent.

When a vocabulary decision requires checking published precedent (UST index, glossaries, or issues_resolved), record it in data/quick-ref/ust_decisions.csv for future reference. Only record non-trivial decisions -- common words that map obviously don't need tracking.

# Check if decision already recorded
grep "H2617" data/quick-ref/ust_decisions.csv 2>/dev/null

# Append new decision (creates file with header if needed)
echo "H2617,chesed,faithful love,PSA,dominant UST rendering 67%,,$(date +%Y-%m-%d)" >> data/quick-ref/ust_decisions.csv

D. Active Voice

Every passive construction must be converted to active voice.

Detection pattern: auxiliary (be/is/are/was/were/been/being) + past participle

If you cannot identify the agent, use:

• Generic agent: "Someone told...", "People will..."
• Intransitive alternative: "they will die" instead of "they will be killed"
• God as agent (divine passive): "God will judge them"

E. Abstract Nouns to Verbal Forms

When identified issues flag figs-abstractnouns, convert the abstract noun to a verbal or clausal form:

Ask: What action or quality does this noun represent? Express it as a verb or clause.

F. Nominalized Adjectives

When identified issues flag figs-nominaladj, unpack the nominalized adjective into its full meaning:

The UST should make clear who or what is being described.

G. Figurative Language (Metaphors, Similes)

When the issues file flags figs-metaphor or figs-simile, or T4T markers [MET]/[SIM] are present:

1. Identify what the figure means (what is actually happening or being described)
2. Write that meaning in plain, non-figurative English
3. Do NOT preserve the image, even if it "sounds better"
4. Do NOT introduce new English metaphors or similes that weren't in the source
5. Do NOT substitute an English idiom that encodes the same concept as the Hebrew metaphor — if the Hebrew uses a path/way metaphor for "life direction," don't write "blocked every way forward" because "way forward" is the same metaphor in English dress. Write what actually happened: "prevented me from making any progress" or "frustrated everything I tried to do."
6. When T4T uses "It is as though" framing, the ENTIRE content after that phrase is figurative. Do not drop the framing words and then state the imagery as literal fact. Instead, identify what the figure describes and state that plainly. Example: T4T "It is as though he shot arrows into my body" → BAD: "He shot his arrows deep into my body" (stated as fact) → GOOD: "He deliberately caused me intense suffering."

H. Psalm Superscriptions

(See Active Voice above for passive → active conversion)

Superscription verse anchoring: Do not assume all psalm headings belong in \d before verse 1. Anchor placement to the Hebrew chapter structure:

1. If Hebrew \v 1 contains both superscription and body text (e.g., Psalms 120-134 "song of ascents" + body), the superscription is part of verse 1. Output as:

   \d
   \v 1 A song of ascents.
   \q1 Yahweh, remember David
   \q2 and all of the difficulties that he had.
   

   \d is an empty paragraph-style marker (tells renderers to style what follows as a superscription). \v 1 contains just the superscription text. \q1 starts the poetry body, still part of verse 1. Do NOT put text on the \d line, do NOT put \d after \v 1, and do NOT omit \d.

2. If Hebrew has superscription words only in \v 1 (no body text until \v 2), with verse-offset markers showing English versification is shifted (Hebrew v2 = English v1), keep the superscription on \d with its text and start body at English \v 1:

   \d This is for the chief musician. It is a psalm of David.
   \v 1 All the people on the earth, shout joyfully to God!
   

Quick check at chapter start:

• Read the first 5-10 lines after \c N in Hebrew.
• If \v 1 has both superscription words AND body text: use format 1 (empty \d, superscription in \v 1).
• If \v 1 has only superscription words and body starts at \v 2: use format 2 (\d with text, body at English \v 1).

I. Initial Conjunctions

If T4T starts sentences with "And" or "But", replace:

• "And" → "So" / "Then" / remove
• "But" → "However" / remove

Step 5: Verify Against Standards

Cross-check with:

• reference/ust_patterns.md - transformation patterns
• ../reference/gl_guidelines.md - shared style rules (formality, numbers, spelling, comparisons)

{Brackets} - Use Sparingly:

• Most clarifying information should be woven into natural prose without brackets
• Only bracket content that is truly unexpressed in the source AND essential for comprehension
• Length limit: Should not be as long as a regular sentence
• When in doubt, write naturally without brackets
• Exception: short verse-initial framing clauses from implied context may be bracketed (e.g., {As I travel toward Jerusalem,})

Step 6: Format as USFM

Ensure proper USFM formatting:

\id [BOOK] - unfoldingWord Simplified Text
\usfm 3.0
\h [Book Name]
\toc1 [Full Book Name]
\toc2 [Abbreviated Name]
\toc3 [Short Code]
\mt [Main Title]

\c [chapter]
\p
\v [verse] [text]

\q1 [poetry line 1]
\q2 [poetry line 2 - indented]

Poetry markers:

• \q1 - first colon of a verse
• \q2 - second/third colon (parallel lines)
• \d - superscription (Psalms, only when Hebrew has standalone heading)
• \qs ... \qs* - Selah

Step 7: Export to File

Save to output/AI-UST/ with naming convention:

output/AI-UST/[BOOK]/[BOOK]-[CHAPTER].usfm

Step 7.5: Write Alignment Hints

After writing the UST USFM, write a hints JSON that records which Hebrew words you rendered in each English phrase. As you generated each phrase, you knew which Hebrew concepts you were rendering -- capture that mapping now.

Output path: output/AI-UST/hints/<BOOK>/<BOOK>-<CH>.json

Format:

[
  {
    "reference": "PSA 1:1",
    "hints": [
      {"english": "The person who will have a truly good life", "hebrew_indices": [0, 1]},
      {"english": "is the person who", "hebrew_indices": [2]},
      {"english": "does not do what evil people tell him to do,", "hebrew_indices": [3, 4, 5, 6]},
      {"english": "{It seems like}", "hebrew_indices": [], "implied": true}
    ]
  }
]

Rules:

• One entry per verse
• english = phrase from the UST, matching english_text word-for-word
• hebrew_indices = which Hebrew word positions (0-based) contributed meaning to that phrase
• Add "implied": true on entries with bracketed content (hebrew_indices: [])
• Phrases should cover all English words (complete coverage)
• Granularity: phrase-level, not word-level. Group by the meaning units you were thinking in.
• This is a rough draft for the aligner, not a finished alignment. Don't overthink it.

Step 8.5: Check for Passive Voice

Run mcp__workspace-tools__check_ust_passives on output/AI-UST/[BOOK]/[BOOK]-[CHAPTER].usfm.

If passives are found (exit code 1), fix them before proceeding. The script prints each passive phrase with its verse reference to stderr.

Step 8: Convert to Curly Quotes

Run mcp__workspace-tools__curly_quotes with inPlace: true to normalize quotes.

This converts:

• Straight double quotes "..." to curly "..."
• Straight single quotes/apostrophes '...' to curly '...'

Scripts Reference

Fetch T4T (primary source)

Use mcp__workspace-tools__fetch_t4t with books=["PSA", "1KI"] (or omit books to list available).

Vocabulary lookup

Use Grep for quick text lookups in:

• data/issues_resolved_optimized.txt (or data/issues_resolved.txt)
• data/quick-ref/ust_decisions.csv
• data/glossary/*.csv

When comparing T4T to ULT, prefer chapter reads from mcp__workspace-tools__read_usfm_chapter using the authoritative ULT path from context when available.

For steps 3 and 4 (UST Strong's index), use mcp__workspace-tools__build_ust_index with lookup="H2617" or compare="H2617".

UST Strong's Index

Use mcp__workspace-tools__build_ust_index with optional parameters:

• lookup="H2617" — look up published UST renderings for a Strong's number
• compare="H2617" — compare ULT (literal) vs UST (meaning-based) renderings
• stats=true — index statistics
• No parameters — build/refresh UST index (daily staleness check)

Alignment and Hebrew verification

If alignment data is needed, use the aligned ULT supplied by the pipeline context or the workspace MCP alignment tools. Do not rely on ad hoc shell scripts or /tmp files.

Quality Checklist

Before finalizing UST output, verify:

T4T Conversion:

• T4T notation markers removed ([IDI], [DOU], [SYN], [RHQ], [EUP], [MTY], [MET], [SIM])
• \add...\add* content woven into natural prose (rarely bracketed)
• Changes are minimal - T4T preserved where it meets standards
• Figurative language expressed as plain meaning — no preserved metaphors, similes, or Hebrew idioms; no new English metaphors introduced

unfoldingWord Standards:

• Divine names correct (Yahweh, not LORD)
• Same proper names as ULT (no modern equivalents)
• No sentences starting with "And" or "But"
• No passive voice (search for: is/are/was/were/been/being + past participle)
• Abstract nouns converted to verbal/clausal forms where flagged
• Nominalized adjectives unpacked (not just "the dead" but "dead people" or similar)
• Key vocabulary matches Issues Resolved decisions

Style:

• Natural English word order
• Clear, common vocabulary
• {brackets} used sparingly - only for truly unexpressed, essential content
• Most clarifications woven into natural prose without brackets
• USFM markers properly formatted
• Superscription placement matches Hebrew anchoring (\v 1-embedded vs standalone \d)
• Poetry uses \q1/\q2 appropriately
• "peoples" kept as "peoples"
• Selah retained as "Selah"

Data Sources (Runtime Lookups)

Always check these at runtime - do not rely on memory:

Note: data/published_ust/ contains older UST that may not meet current standards. Use T4T as your base, not published UST. The UST Strong's index is still useful for seeing how published UST renders specific Hebrew words -- treat it as precedent to consider, not authority to follow. Likewise, when context.json is present, its ULT path overrides any published-ULT fallback.

Related Skills

• Pipeline Overview - Where this fits in the workflow
• ULT-gen - Literal translation (form-based)
• Issue Identification - Finding translation issues
• Hebrew Reference - Hebrew language patterns