mlb-beginner-translator

What this skill does

# MLB Beginner Translator

## Table of Contents
- [Example](#example)
- [Workflow](#workflow)
- [Common Patterns](#common-patterns)
- [Guardrails](#guardrails)
- [Quick Reference](#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](#guardrails)).
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](resources/methodology.md#jargon-detection-checklist) 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](resources/methodology.md#first-mention-rule) for the rule, and [resources/template.md](resources/template.md#inline-gloss-patterns) 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](resources/methodology.md#common-traps) and [Guardrails #2](#guardrails) 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](/Users/kushaldsouza/Documents/Projects/yahoo-mlb/CLAUDE.md) rule 6. If the upstream agent hedged,