mlb-beginner-translator

MLB Beginner Translator

Table of Contents

• Example
• Workflow
• Common Patterns
• Guardrails
• Quick Reference

Example

Scenario: The lineup-optimizer has produced a raw recommendation that needs to be rewritten for the user (K L D'Souza, zero baseball knowledge) before it ships in the morning brief.

Before (raw, jargon-heavy):

Caminero (TB 3B) has positive platoon splits vs RHP and a plus matchup vs Bello at Fenway (park factor 103 R / 105 HR). His 15-day xwOBA is .410 vs a .355 baseline, suggesting a hot streak. OBP contribution is elite given his #3 slot. daily_quality = 66. SB opportunity is middling -- Bello holds runners average but catcher CS% 28%. Regression index +15 on season wOBA gap. START over Hayes (UTIL), who faces a LHP in a bullpen game at Oracle -- negative park, low opportunity, QS unlikely (trivially, he is a hitter; what I mean is his slate has low floor). Verdict: START Caminero, SIT Hayes.

After (beginner-translated):

Junior Caminero (Tampa Bay, third base) -- START him today.

Why: he hits right-handed pitchers well (most batters hit better against pitchers who throw from the opposite hand), and today's opposing pitcher (Brayan Bello) throws right-handed. The stadium (Fenway Park in Boston) also favors hitters -- it gives about 3% more runs and 5% more home runs than an average park. On top of that, Caminero has been hitting well lately (his expected-hitting quality over the last 15 days is about 15% above his season average), and he is batting third in the lineup (more times at the plate = more chances to score). Stealing a base today is a coin flip -- the Boston catcher throws out runners at a decent rate, so we are not counting on it.

Ke'Bryan Hayes (Pittsburgh, third base, in your utility slot) -- SIT him today.

Why: he faces a left-handed pitcher, which is the harder matchup for him, and the game is at Oracle Park in San Francisco (a cold, big-outfield park that suppresses hitting). The opposing team is also using a bullpen game (no single starter -- they cycle relief pitchers all game), which tends to produce fewer big hitting opportunities.

Actions:

• START Caminero at 3B.
• SIT Hayes (move him to bench, BN).

What the translator did:

1. Detected 11 jargon terms (RHP, platoon splits, park factor, xwOBA, OBP contribution, daily_quality, SB, CS%, regression index, bullpen game, QS) and either glossed each on first use or rewrote around them.
2. Rewrote "hot streak" as "has been hitting well lately" (see Guardrails #2).
3. Dropped internal agent signals (daily_quality = 66, regression_index = +15) -- these are inputs, not output.
4. Collapsed the decision to action verbs (START / SIT) at the end.
5. Kept position abbreviations (3B, BN) only after the position was spelled out in parentheses on first use.
6. Removed the self-correction ("trivially, he is a hitter...") -- the user does not need to see the agent debating itself.

Workflow

Copy this checklist and track progress:

MLB Beginner Translator Progress:
- [ ] Step 1: Receive raw draft from upstream agent
- [ ] Step 2: Scan for jargon terms (use glossary list)
- [ ] Step 3: Apply first-mention-gloss rule per term per document
- [ ] Step 4: Rewrite assumed-knowledge phrases (hot streak, plus matchup, etc.)
- [ ] Step 5: Strip internal signals and agent self-talk
- [ ] Step 6: Collapse to action verbs (START / SIT / ADD / DROP / BID $X / ACCEPT / COUNTER / REJECT)
- [ ] Step 7: Validate against rubric (resources/evaluators)

Step 1: Receive raw draft from upstream agent

Accept whatever the calling agent produced -- lineup-optimizer synthesis, trade-analyzer verdict, waiver-analyst ranking, category-strategist plan, coach's morning brief. The input can be bullet points, prose, or a signal JSON block; output is always user-facing prose plus an action list.

• Identify the document type (brief, trade memo, chat reply, alert)
• Identify every player named -- each first mention must include team and position
• Identify every recommendation -- each must end in an action verb

Step 2: Scan for jargon terms

Walk through the full glossary in resources/methodology.md and the master context/frameworks/beginner-glossary.md in the yahoo-mlb repo. Mark every occurrence of every term. A term can appear in five forms: full word ("On-Base Percentage"), initialism ("OBP"), compound ("OBP contribution"), slang ("hot bat"), and internal signal name ("daily_quality"). All five count as jargon.

• Category stats detected (R, HR, RBI, SB, OBP, K, ERA, WHIP, QS, SV)
• Position abbreviations detected (C, 1B, 2B, 3B, SS, OF, UTIL, SP, RP, P, BN, IL, DH)
• Matchup terms detected (RHP, LHP, platoon, park factor, probable, lineup, two-start, bullpen game, opener, streaming)
• Advanced stats detected (xwOBA, wOBA, BABIP, FIP, xFIP, SIERA, barrel rate, exit velocity)
• Transaction terms detected (FAAB, waivers, rolling waivers, H2H, punt, IL stash, DFA, handcuff)
• Archetypes detected (sleeper, bust, breakout, post-hype, innings-eater, closer committee)
• Internal signal names detected (daily_quality, form_score, matchup_score, regression_index, qs_probability, streamability_score, etc.)

Step 3: Apply first-mention-gloss rule per term per document

For every jargon term detected in Step 2, attach an inline parenthetical plain-English gloss the first time the term appears in the document. Subsequent mentions in the same document can use the bare term. See resources/methodology.md for the rule, and resources/template.md for the gloss patterns.

• Every first mention is immediately followed by "(plain-English description)"
• Subsequent mentions do not repeat the gloss (avoids reader fatigue)
• Player names are always accompanied by team and position on first mention

Step 4: Rewrite assumed-knowledge phrases

The dangerous category is not unfamiliar words -- it is familiar-sounding phrases that secretly assume baseball knowledge. "Hot streak," "good matchup," "plus matchup," "tough lefty," "soft slate," "live arm," "plays the hot corner," "juicy park." Each of these requires a rewrite, not a gloss. See resources/methodology.md and Guardrails #2 for the full list and rewrite patterns.

• "Hot streak" / "hot bat" -> "has been hitting well lately"
• "Plus/positive matchup" -> named concrete reason (park, opposing pitcher hand, weather)
• "Tough lefty" -> "a good left-handed pitcher"
• "Juicy park" -> "a stadium that favors hitters (specific park named)"
• "Bat flip / gas / heater / nasty" -> rewrite in literal terms

Step 5: Strip internal signals and agent self-talk

Internal signal values (numeric daily_quality, regression_index, streamability_score) are inputs to the decision, not content for the user. Drop them. Also drop any self-correction, debate remnants, or variant labels ("the advocate says... the critic says... synthesis is..."). The user sees only the synthesized answer.

• Numeric signal values removed from user-facing prose
• Variant labels removed ("advocate / critic / synthesis")
• Self-corrections removed ("trivially," "what I mean is," "to be clear")
• Confidence labels kept only if expressed in plain English ("high confidence" ok; "confidence: 0.72" not ok)

Step 6: Collapse to action verbs

Every recommendation must end in one of the approved action verbs with no hedging. No "consider," "think about," "might want to," "could try." See the full ladder in CLAUDE.md rule 6. If the upstream agent hedged, collapse the hedge into a single verb plus an explicit fallback action.

• Every recommendation ends in: START / SIT / ADD / DROP / BID $X / ACCEPT / COUNTER (with suggested counter) / REJECT
• A dedicated "Actions" bullet list appears at the end of every user-facing output
• Hedges ("consider," "think about") replaced with a concrete verb + fallback

Step 7: Validate against rubric

Score the translated output against resources/evaluators/rubric_mlb_beginner_translator.json. Minimum standard: average score of 4.0, and no criterion scored below 3. If the action-verb criterion or the first-mention-rule criterion scores below 4, revise before shipping.

• Rubric scored, every criterion at 3 or higher
• Average at 4.0 or above
• Action-verb and first-mention-rule criteria at 4 or higher

Common Patterns

Pattern 1: Daily lineup brief (morning)

• Input shape: list of players with daily_quality scores, matchup notes, confirmed/unconfirmed lineup status
• Output shape: one short paragraph per player, then a consolidated action list at the end
• Critical rewrites: daily_quality score dropped; matchup terms (park factor, RHP/LHP, platoon) glossed; "confirmed" explained as "in today's lineup card"
• Ends in: START / SIT per player, with position slot named

Pattern 2: Trade recommendation memo

• Input shape: trade offer (players in / players out), category impact table, synthesis from mlb-trade-analyzer
• Output shape: one-line summary of the offer, short "why" in plain English, a category impact paragraph ("you gain power, you lose speed"), then a single action verb
• Critical rewrites: category names spelled out (HR -> home runs; SV -> saves by relief pitchers); archetypes (sleeper, breakout) translated; roster fit (SS / OF eligibility) explained
• Ends in: ACCEPT / COUNTER (with suggested counter) / REJECT

Pattern 3: Waiver / FAAB add memo

• Input shape: player recommendation, FAAB bid, category gap filled, drop candidate
• Output shape: why the player is available (injury to starter, breakout, etc.), how much to bid in dollars, who to drop
• Critical rewrites: FAAB explained on first mention; "waivers" explained; "handcuff" translated as "backup closer"; percentages expressed as "roughly X of Y starts"
• Ends in: BID $X on Player (drop Player Y) / PASS

Pattern 4: Weekly category-strategy plan

• Input shape: category state (leading / losing / tied), punt decisions, streaming schedule
• Output shape: week preview -- "here is where you stand this week" -- followed by specific category actions
• Critical rewrites: H2H explained; "punt" explained as "give up on a category to dominate others"; "streaming" explained as "rotating pitchers based on matchups"; QS explained
• Ends in: Actions for each lever (START X on Tue, DROP Y, ADD Z via FAAB)

Pattern 5: Chat reply (ad hoc question)

• Input shape: a user question ("should I drop Arraez?"), agent signals, variant debate
• Output shape: a 1-3 sentence answer plus the action
• Critical rewrites: Do not dump signals; do not narrate the agent debate; answer in the user's language
• Ends in: a single action verb

Guardrails

1. The first-mention-gloss rule is per document, not per sentence. Once you have glossed OBP in the first paragraph, you do not re-gloss it in paragraph four of the same document -- that would annoy the reader. But if the document is a fresh morning brief, every jargon term resets. When in doubt, err toward glossing again in a new document.

2. Watch for "hot streak" traps. The phrase "hot streak" sounds self-explanatory but assumes the user knows baseball performance is noisy and streaky. Rewrite as "has been hitting well over the last 1-2 weeks" or "has been pitching well lately." Equivalent traps: "cold streak" -> "has been struggling lately"; "plus matchup" -> name the concrete reason (opposing pitcher, park, weather); "tough lefty" -> "a good left-handed pitcher"; "juicy park" -> name the park and say "favors hitters"; "live arm" -> "throws hard with good movement."

3. Never use an internal signal name in user output. daily_quality, form_score, matchup_score, opportunity_score, regression_index, streamability_score, qs_probability, obp_contribution, sb_opportunity, role_certainty, k_ceiling, era_whip_risk, two_start_bonus, save_role_certainty -- all of these are internal. They are inputs to your decision, not content for the user. If you must convey the idea ("he has been unusually unlucky and is due to improve"), use plain English.

4. Every player's first mention in a document gets team + position. "Junior Caminero (Tampa Bay, third base)" not "Caminero." After the first mention, the last name alone is fine. Applies to every document type.

5. Action verbs are not optional. The user cannot interpret "consider starting Caminero if the weather holds" -- the user has no model of what "if the weather holds" means. Collapse to a primary action plus an explicit fallback: "START Caminero; if the game is postponed, swap in Hayes." No "consider," "think about," "might want to," "could try," "lean toward," "leaning," "in play."

6. Dollars, not percentages, for FAAB. The user has a $100 budget. Say "bid $12" not "bid 12% of remaining FAAB." If the context requires a percentage, translate to dollars explicitly.

7. Category codes get spelled out on first use. "HR" is not a baseball term to a beginner -- it is two letters. Write "home runs (HR)" the first time, then "HR" thereafter. Same for R, RBI, SB, K, SV, QS, and even OBP / ERA / WHIP which look familiar but are not.

8. Do not invent jargon translations. If an upstream agent uses a term that is not in the master glossary (context/frameworks/beginner-glossary.md) or the extended list in resources/methodology.md, either (a) ask the upstream agent to rephrase, or (b) rewrite around the term using only glossary-approved words. Do not freelance a new plain-English gloss -- glossary consistency matters across briefs.

9. Degrade gracefully on unverified facts. If the upstream agent's draft includes a fact marked confidence: low or a fact that could not be web-verified, surface the uncertainty in plain English ("I could not verify the weather forecast for San Francisco today -- if the game is postponed, see fallback below"). Never hide the uncertainty.

10. Do not add emojis or decorations. The user asked for plain English, not performative friendliness. Bold for player names and action verbs is allowed. Emojis, smileys, and cheerleader phrases ("great pick!") are not.

Quick Reference

The action-verb ladder (from CLAUDE.md rule 6):

START             -- put this player in your active lineup today
SIT               -- bench this player today (move to BN)
ADD               -- claim this player (via FAAB or waivers)
DROP              -- release this player from the roster
BID $X            -- submit a FAAB bid of $X (between $0 and remaining budget)
ACCEPT            -- accept the incoming trade offer as-is
COUNTER           -- reject as-is and send back a specific counter (specify the counter)
REJECT            -- reject the incoming trade offer with no counter
PASS              -- do not claim this player (alternative to ADD on waivers)

The first-mention-gloss pattern:

<bare term> -> <term> (<plain-English description>) on first mention in a document
             -> <bare term> on subsequent mentions in the same document

Example:

• First mention: "Junior Caminero's OBP (how often he gets on base via hits, walks, or hit-by-pitches) is .360."
• Later mention: "Caminero's OBP is trending up."

Common rewrites (assumed-knowledge phrases):

Agent phrase	User-facing rewrite
"Hot streak"	"Has been hitting well over the last 1-2 weeks"
"Cold streak"	"Has been struggling lately"
"Plus matchup"	Name the concrete reason (park, pitcher hand, weather)
"Tough lefty"	"A good left-handed pitcher"
"Juicy park"	"Stadium that favors hitters ()"
"Live arm"	"Throws hard with good movement"
"Has the hot hand"	"Is in a good stretch of games"
"Good slate"	"Plays today in a favorable setup"
"Ace"	"One of the best starting pitchers in baseball"
"Stud"	"Top-tier player"
"Bat flip / dinger / dong"	"Home run"
"Gas / cheese / heater"	"Fastball"
"Punch out"	"Strikeout"
"Free pass / walk"	"Walk (pitcher gives up a base without a hit)"

Key resources:

• resources/template.md: Inline gloss patterns by term category (stats, positions, matchups, advanced, transactions, archetypes, signal names). Before/after translation templates for briefs, trade memos, waiver memos, chat replies.
• resources/methodology.md: The first-mention rule, assumed-knowledge trap list, action-verb enforcement, worked before/after examples including a full lineup recommendation with jargon and without.
• resources/evaluators/rubric_mlb_beginner_translator.json: 10-criterion rubric (jargon detection, gloss accuracy, first-mention rule, assumed-knowledge rewrites, signal stripping, action-verb presence, player identification, uncertainty surfacing, tone, overall readability).
• Master glossary: yahoo-mlb/context/frameworks/beginner-glossary.md -- authoritative source for plain-English definitions. This skill mirrors and extends it.

Inputs required:

• Raw draft from an upstream MLB agent (coach, lineup-optimizer, waiver-analyst, trade-analyzer, category-strategist, streaming-strategist, playoff-planner)
• The target document type (brief, trade memo, waiver memo, category plan, chat reply)
• Any confidence: low flags from web-search failures upstream

Outputs produced:

• A fully translated user-facing document: every jargon term glossed on first use, every assumed-knowledge phrase rewritten, every internal signal stripped, every recommendation collapsed to action verbs.
• A consolidated "Actions" bullet list at the end.
• Optional uncertainty notes in plain English for any unverified facts.