ust-gen

name	UST-gen
description	Transform T4T into unfoldingWord Simplified Text (UST), communicating the original meaning in natural English. Use when asked to create UST, generate simplified text, or transform T4T.
allowed-tools	Read, Grep, Glob, mcp__workspace-tools__*

MCP-First Execution

In restricted runs, use workspace MCP tools instead of shell/python snippets:

• mcp__workspace-tools__fetch_t4t, mcp__workspace-tools__fetch_door43
• mcp__workspace-tools__read_usfm_chapter — read a single chapter from a book file (use this instead of reading full books)
• mcp__workspace-tools__build_ust_index
• mcp__workspace-tools__check_ust_passives
• mcp__workspace-tools__curly_quotes

Pipeline Context

If --context <path> is provided, read the context.json file first. Treat it as authoritative.

Use these fields when present:

• sources.ult — authoritative ULT for this chapter. In the normal pipeline this is the just-generated, issue-reviewed ULT. In UST-only runs the pipeline runner has already chosen between the freshest local generated ULT and freshly fetched en_ult master.
• sources.ultFull — full-book ULT file when the runner fetched one
• sources.hebrew — Hebrew source path
• sources.issues — authoritative issues TSV path when available

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.

ULT	Bad UST (too similar)	Good UST (differentiated)
"He gave over their cattle to the hail"	"He gave over their cattle to the hail"	"He let the hail kill their cattle"
"and their livestock to the bolts of lightning"	"and their livestock to the bolts of lightning"	"and he let lightning strike their livestock"
"They tested God in their heart"	"They tested God in their heart"	"They challenged God to see if he would help them"
"by asking for food for their craving"	"by asking for food for their craving"	"by demanding the food they wanted"

Simpler Vocabulary

Prefer common words over formal/literary ones:

ULT/Formal	UST/Simple
livestock	animals / herds
craving	desire / want
iniquity	sin / evil
transgressions	sins
rebuke	correct / scold
wrath	anger
affliction	suffering / trouble
insolent	proud / arrogant
abhor	hate / reject
slumber	sleep
give over to	let X destroy / hand over to

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.

ULT (parallel lines)	UST (collapsed)
"He gave over their cattle to the hail / and their livestock to the bolts of lightning"	"He sent a terrible thunderstorm with hail to kill all their cattle"
"They did not keep the covenant of God / and they refused to walk in his law"	"They refused to obey God's covenant and law"
"Yahweh knows the way of the righteous / but the way of the wicked will perish"	Keep both - this is antithetic parallelism (contrast), not synonymous

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

Marker	Meaning	UST Implication
\add...\add*	Implicit information	Usually weave into prose; rarely bracket
[IDI]	Idiom	Render the meaning, not literal form
[DOU]	Doublet (repetition for emphasis)	May simplify or keep both terms
[SYN]	Synecdoche (part for whole)	Express the intended referent
[RHQ]	Rhetorical question	Keep as question or convert to statement
[EUP]	Euphemism	Use clear language
[MTY]	Metonymy (association)	Express what is actually meant
[MET]	Metaphor	State the plain meaning; do not preserve the image
[SIM]	Simile	State the plain meaning; do not preserve the comparison

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	UST
\add text \add*	Evaluate: most become unbracketed natural prose
[IDI], [DOU], etc.	Remove entirely
[RHQ]	Remove (keep the rhetorical question)

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

ULT/T4T (passive)	UST (active)
"they will be killed"	"they will die" / "someone will kill them"
"will be eaten by jackals"	"jackals will eat"
"A psalm written by David"	"David wrote this song"
"it was told to Solomon"	"Someone told Solomon"

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:

Abstract (ULT/T4T)	Verbal (UST)
"the salvation of Yahweh"	"how Yahweh saves"
"his righteousness"	"how righteous he is"
"the fear of Yahweh"	"to deeply respect Yahweh"
"covenant faithfulness"	"You are always kind to me, as you promised"
"his power and glory"	"how powerful and glorious you are"

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:

Nominalized (ULT/T4T)	Unpacked (UST)
"the wicked"	"wicked people" / "people who do evil"
"the righteous"	"righteous people" / "people who do what is right"
"the dead"	"dead people" / "people who have died"
"the poor"	"poor people" / "people who are poor"

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

Hebrew figure	BAD (preserved/new metaphor)	GOOD (plain meaning)
"breath of our nostrils" (king)	"as essential as the breath in our nostrils"	"the one who kept us alive"
"poured out his anger"	"poured out his fierce anger"	"showed how extremely angry he was"
"drink from the cup of anger"	"drink from the cup of his anger"	"Yahweh will punish you severely"
"purer than snow, whiter than milk"	"brighter than snow, whiter than milk"	"very pure and healthy-looking"
"wrapped in anger"	"wrapped yourself in anger"	"because you were angry"
"streams of water from my eye"	"tears like streams of water"	"many tears flow from my eyes"
"saturated with wormwood"	"drenched me in misery"	"caused me to suffer greatly"
"walled up my ways with stone"	"blocked every way forward" (English path idiom)	"prevented me from making any progress"
"a bear lying in ambush"	"waited in hiding" (still figurative)	"attacked me suddenly and without warning"
"he bent his bow / shot arrows into my body"	"He shot his arrows deep into my body" (literal fact)	"He deliberately caused me intense suffering"
"made my teeth grind on gravel / pressed me in ashes"	"made me chew on gravel / pushed my face in ashes" (literal fact)	"He completely humiliated and degraded me"

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:

Source	Path	Purpose
T4T	data/t4t/*.usfm	PRIMARY SOURCE for UST
Issues Resolved	data/issues_resolved_optimized.txt	FINAL AUTHORITY - UST decisions (topically organized; fallback: data/issues_resolved.txt)
Hebrew Glossary	data/glossary/hebrew_ot_glossary.csv	UST_GLOSS column
Psalms Reference	data/glossary/psalms_reference.csv	UST_GLOSS column
Sacrifice Terms	data/glossary/sacrifice_terminology.csv	UST_GLOSS column where available
Measurements	data/glossary/biblical_measurements.csv	UST_GLOSS column where available
Biblical Phrases	data/glossary/biblical_phrases.csv	UST_GLOSS column where available
Context ULT	context.json -> sources.ult	Meaning verification (authoritative when present)
UST Strong's Index	data/cache/ust_index.json	Published UST renderings by Strong's number
UST Decisions	data/quick-ref/ust_decisions.csv	Prior UST vocabulary decisions
UST Patterns	reference/ust_patterns.md	Transformation rules
Style Guide	../reference/gl_guidelines.md	Shared style rules

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