mlb-category-state-analyzer

What this skill does

# MLB Category State Analyzer

## Table of Contents
- [Example](#example)
- [Workflow](#workflow)
- [Common Patterns](#common-patterns)
- [Guardrails](#guardrails)
- [Quick Reference](#quick-reference)

## Example

**Scenario**: Week 3, K L's Boomers (Team 5) vs. Los Doyers. Wednesday AM (mid-week). 4 scoring days remain.

**Raw matchup scores (pulled from Yahoo matchup page)**:

| Cat | Us | Opp | Margin | Games left (us/opp) |
|---|---|---|---|---|
| R | 28 | 31 | -3 | 26 / 22 |
| HR | 9 | 7 | +2 | 26 / 22 |
| RBI | 30 | 29 | +1 | 26 / 22 |
| SB | 4 | 6 | -2 | 26 / 22 |
| OBP | .342 (82 PA) | .336 (78 PA) | +.006 | 26 / 22 GP |
| K | 42 | 38 | +4 | 9 SP starts / 7 SP starts |
| ERA | 3.80 (21 IP) | 4.12 (19 IP) | -0.32 (better) | 9 / 7 |
| WHIP | 1.18 (21 IP) | 1.25 (19 IP) | -0.07 (better) | 9 / 7 |
| QS | 2 | 1 | +1 | 9 / 7 |
| SV | 3 | 5 | -2 | ~8 RP days / ~8 RP days |

**Projections built for the sim** (rest-of-week `{mean, stddev}` — see [resources/methodology.md](resources/methodology.md#building-per-cat-projection-dicts)):

| Cat | Our projection | Opp projection |
|---|---|---|
| R | final 52 ± 9 | final 57 ± 8 |
| HR | final 15 ± 3.5 | final 13 ± 3.2 |
| RBI | final 52 ± 9 | final 55 ± 8 |
| SB | final 6 ± 2.3 | final 10 ± 2.5 |
| OBP | .346 ± .015 | .341 ± .014 |
| K | final 96 ± 11 | final 85 ± 10 |
| ERA | 3.88 ± 0.40 | 4.05 ± 0.45 |
| WHIP | 1.20 ± 0.07 | 1.25 ± 0.08 |
| QS | final 6.1 ± 1.5 | final 3.8 ± 1.4 |
| SV | final 4.8 ± 1.4 | final 7.7 ± 1.5 |

**Delegate to `matchup-win-probability-sim`** with:
- `cat_list = [R, HR, RBI, SB, OBP, K, ERA, WHIP, QS, SV]`
- `cat_inverse_list = [ERA, WHIP]`
- `cat_win_threshold = 6`
- `our_per_cat_projection` / `opp_per_cat_projection` from the table above
- `sim_mode = "monte_carlo"`, `n_simulations = 10000`, `random_seed = 42`

**Sim output (consumed by this skill)**:
- `matchup_win_probability = 0.58`
- `per_cat_win_probability`: R 0.36, HR 0.65, RBI 0.42, SB 0.16, OBP 0.60, K 0.74, ERA 0.62, WHIP 0.68, QS 0.85, SV 0.10
- `expected_cats_won = 5.18`

**Per-cat signals (derived here from sim output + baseball state — see [resources/methodology.md](resources/methodology.md#signal-formulas))**:

| Cat | Position (from state) | Pressure (state + pace) | Reachability (= round(100 × p_cat)) | Punt Score (= f(1 − p_cat) + volatility) | Verdict |
|---|---|---|---|---|---|
| R | losing | 72 | 36 | 44 | push (contested) |
| HR | winning | 48 | 65 | 21 | maintain |
| RBI | winning (thin) | 65 | 42 | 35 | push |
| SB | losing | 55 | 16 | 58 | evaluate punt |
| OBP | winning (thin) | 70 | 60 | 24 | push |
| K | winning | 55 | 74 | 16 | push |
| ERA | winning | 62 | 62 | 23 | push |
| WHIP | winning | 60 | 68 | 19 | maintain |
| QS | winning | 78 | 85 | 9 | push hard |
| SV | losing | 38 | 10 | 84 | punt |

**Overall recommendation**: **Push 6, maintain 2, punt 2.** Matchup win prob 58% (neutral favorite).

- **Push (6)**: HR, OBP, K, ERA, QS — each has `per_cat_win_probability ≥ 0.60`. Plus RBI as the contested-but-reachable 6th.
- **Maintain (2)**: WHIP (locked-ish), R (reachability lowish but not a true punt).
- **Punt (2)**: SB (p = 0.16, low reach) and SV (p = 0.10 + volatility bonus → punt score 84).

**Downstream implications for other agents**:
- Lineup optimizer: `matchup_win_probability = 0.58` → neutral-to-favorite, standard daily_quality optimization (no variance tilt).
- Waiver analyst: prioritize SP (QS, K, ERA), OBP-heavy bats; not closers or speed specialists.
- Streaming strategist: every QS-capable SP starts; skip any 5-inning risk arm.

## Workflow

Copy this checklist and track progress:

```
MLB Category State Analysis Progress:
- [ ] Step 1: Pull current matchup scores from Yahoo
- [ ] Step 2: Count remaining games/PAs/IP for both rosters
- [ ] Step 3: Build per-cat projection dicts ({mean, stddev}) for both rosters
- [ ] Step 4: Delegate to matchup-win-probability-sim (pass cat_list, projections, threshold=6, inverse=[ERA,WHIP])
- [ ] Step 5: Derive cat_position (from state), cat_pressure, cat_reachability, cat_punt_score from sim output
- [ ] Step 6: Rank cats and emit push/maintain/punt plan
- [ ] Step 7: Write signal file with YAML frontmatter (include matchup_win_probability from sim)
```

**Step 1: Pull current matchup scores**

Web-fetch the Yahoo matchup page: `https://baseball.fantasysports.yahoo.com/b1/23756/5/matchup?week=N`. Extract current totals for both teams in each of the 10 cats. For ratio cats (OBP, ERA, WHIP), also capture the denominator (PAs for OBP, IP for ERA/WHIP). This is **required** — you cannot build a ratio-cat projection without the volume underlying the ratio.

- [ ] 5 batting cats: R, HR, RBI, SB, OBP (+ at-bats / plate-appearances)
- [ ] 5 pitching cats: K, ERA, WHIP, QS, SV (+ innings pitched)
- [ ] Source URL cited in signal file

See [resources/methodology.md](resources/methodology.md#pulling-matchup-data-from-yahoo) for scrape procedure and fallback if Yahoo is unreachable.

**Step 2: Count remaining games/PAs/IP**

For each roster, count the number of MLB games its players will play for the rest of the scoring period, and project PAs (hitters) and IP (pitchers).

- [ ] Hitter games remaining: sum of (each rostered hitter's team games × probability they start)
- [ ] Pitcher starts remaining: number of scheduled SP starts for the rest of the week per roster
- [ ] Reliever days remaining: days × eligible RPs (for SV projection)
- [ ] Volume imbalance: if one team has meaningfully more games, that will show up directly in the projection means (and so in `per_cat_win_probability`)

Use MLB.com schedules + probable pitcher grids. See [resources/methodology.md](resources/methodology.md#projecting-remaining-games).

**Step 3: Build per-cat projection dicts**

For each team, build a dict `{cat: {mean, stddev}}` where `mean` is the projected **final** (or remaining, consistently used across both teams — pick one convention) and `stddev` reflects uncertainty given remaining volume.

- [ ] **Counting cats** (R, HR, RBI, SB, K, QS, SV): `mean = current_total + Σ(per-player per-game rate × games remaining × daily_quality)`. `stddev ≈ 0.35 × expected_remaining` as a default CV.
- [ ] **Ratio cats** (OBP, ERA, WHIP): `mean = (current_ratio × current_volume + projected_remaining_ratio × remaining_volume) / total_volume`. `stddev ≈ σ_per_obs / sqrt(total_volume)` — shrinks as total IP/PA grows.
- [ ] Both dicts have identical keys and the exact league `cat_list`.
- [ ] Use OBP (not AVG) and `qs_probability` (not W) from upstream `mlb-player-analyzer` signals — see Guardrails.

See [resources/methodology.md](resources/methodology.md#building-per-cat-projection-dicts).

**Step 4: Delegate to `matchup-win-probability-sim`**

Invoke the sibling skill with a well-formed input payload:

```
inputs to matchup-win-probability-sim:
  cat_list:           [R, HR, RBI, SB, OBP, K, ERA, WHIP, QS, SV]
  cat_inverse_list:   [ERA, WHIP]
  cat_win_threshold:  6
  our_per_cat_projection:  <dict from Step 3>
  opp_per_cat_projection:  <dict from Step 3>
  sim_mode:           "monte_carlo"
  n_simulations:      10000
  random_seed:        42
  tie_rule:           "half"

outputs consumed:
  matchup_win_probability  (float in [0,1])
  per_cat_win_probability  (dict[cat, float])
  expected_cats_won        (float)
  variance_estimate        (float)
```

- [ ] All 10 cats present in both projection dicts
- [ ] `cat_inverse_list = [ERA, WHIP]` (lower-is-better)
- [ ] `cat_win_threshold = 6` (Yahoo 10-cat majority)
- [ ] Seed passed for reproducibility
- [ ] Sim output fields captured and stored for Step 5

**Step 5: Derive per-cat signals from sim output + state**

Apply the formulas in [resources/methodology.md](resources/methodology.md#signal-formulas). The sim owns the probability math; this skill owns the baseball-state interpretation.

- [ ] `cat_position` ∈ {winning, tied, losing} — computed locally from **current totals** (not sim). Ratio-cat direction handled (OBP higher = winni