mlb-category-state-analyzer

MLB Category State Analyzer

Table of Contents

• Example
• Workflow
• Common Patterns
• Guardrails
• 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):

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):

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

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.

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. 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 = winning; ERA/WHIP lower = winning).
• cat_pressure (0–100) — simple arithmetic from position + close-margin + volume-edge + locked-in flags. See pressure formula in Quick Reference.
• cat_reachability (0–100) — now = round(100 × per_cat_win_probability[cat]), taken directly from the sim.
• cat_punt_score (0–100) — (100 × (1 − per_cat_win_probability[cat])) × 0.6 + 30 × is_volatile + 20 × below_min_threshold − 10 × has_spillover, clamped.

Step 6: Rank and emit plan

Rank all 10 cats by cat_pressure × cat_reachability / 100:

• Top 6: push — mark these as priority for waivers, streams, starts
• Middle 2: maintain — hold position, don't overspend
• Bottom 2: evaluate punt — if cat_punt_score > 60, confirm punt; otherwise hold

Goal in H2H Cats is 6-of-10. A defensible plan is "push 6, concede up to 4." See resources/template.md for the output signal format.

Step 7: Write signal file

Write to signals/YYYY-MM-DD-cat-state.md with YAML frontmatter (type: cat-state). Include matchup_win_probability from the sim as a top-level field. Validate with mlb-signal-emitter before persisting.

• All 10 cats present with all 4 signals each
• matchup_win_probability and expected_cats_won recorded in frontmatter
• sim_meta block (sim_mode, n_simulations, random_seed) recorded for reproducibility
• Confidence reflects data quality (lower if Yahoo scrape was partial)
• source_urls includes Yahoo matchup page + MLB.com schedule pages + a reference to the sim skill
• Red-team findings noted (e.g., "Opp has a two-start ace coming that could flip K + ERA + WHIP all at once")

Validate output using resources/evaluators/rubric_mlb_category_state_analyzer.json. Minimum: average score of 3.5 or above.

Common Patterns

Pattern 1: Balanced mid-week state

• Typical Wednesday AM state: 3-4 cats already locked, 3-4 close, 2-3 volatile.
• Action: push the close cats hardest, coast the locked wins, ignore locked losses.
• The sim's per-cat probs already reflect this — cats with p ∈ [0.40, 0.65] are the contested ones.

Pattern 2: Volume-imbalanced matchup

• We have 30 hitter games left, opp has 22. Our counting-cat projection means rise; sim's per_cat_win_probability for R/HR/RBI/SB rises accordingly.
• Action: stack the lineup (fewer off-days, prefer teams playing doubleheaders), bid on streamers. Pressure boost comes from the volume-edge flag, reachability boost comes automatically from the sim.

Pattern 3: Two-start ace incoming (us or them)

• One pitcher's two-start week can swing K, ERA, WHIP, QS simultaneously.
• Encode this in the projection dict: their expected IP and K rise, ERA/WHIP means improve (toward their ERA/WHIP), QS mean rises by ~0.45 per expected QS-quality start.
• The sim then shows 4 pitching cats moving together in per_cat_win_probability deltas.

Pattern 4: Save-category volatility

• SVs are low-frequency; one walkoff blown save flips the category.
• In the projection dict, use a low mean (≤ 2.5/week per locked closer) and moderate stddev (≥ 1.2). The sim will naturally report per_cat_win_probability near 0.1–0.25 when behind by 2+.
• The +30 volatility bonus in cat_punt_score (applied here, not in the sim) pushes SV to punt when sim reachability agrees.

Pattern 5: Ratio-cat "freeze"

• Late in the week, if opp is far below the IP/PA minimum (e.g., has 9 IP on Friday with no more starts), their ratio cats are locked at whatever they have.
• Encode by setting opp ratio-cat stddev near zero and their mean at a punitive-or-forfeited value. The sim then returns per_cat_win_probability ≈ 1.0 for those cats.

Guardrails

1. Never compute OBP/ERA/WHIP from rates alone — always include volume (PA/IP). A .400 OBP in 10 PAs is not better than .342 in 82 PAs. The projection-dict mean/stddev for ratio cats must come from the weighted-average formula; the sim takes those as truth.

2. QS is the #1 category, not Wins. This league uses Quality Starts (6+ IP, ≤3 ER). A 5-inning outing scores zero. When projecting remaining QS, multiply each SP start by its QS probability (from mlb-player-analyzer's qs_probability signal) — don't just count scheduled starts.

3. OBP is the #5 category, not AVG. Walks count. When projecting OBP contribution, use players' OBP (not AVG). A high-BB, low-AVG player like Juan Soto is worth more in this league than his raw hit rate suggests.

4. SV is volatile — trust the punt when signals agree. Unlike counting batting cats, a 2-save deficit with 3 days left has low per_cat_win_probability regardless of roster. Don't fight for saves if the closer role on your roster isn't locked (check save_role_certainty < 70 → automatic punt candidate). The volatility bonus in cat_punt_score is applied here, not in the sim — the sim returns raw probability.

5. cat_reachability comes from the sim — don't recompute. This is a delegation. If the sim returns per_cat_win_probability[R] = 0.36, then cat_reachability[R] = 36. Do not apply z-score shortcuts or best/worst-case buckets here — those lived in the old heuristic and are now owned by the sim skill.

6. Locked-in cats get pressure adjustments, not zero. A locked-in win still has cat_pressure ≈ 40 (it's banked). A locked-in loss still has cat_pressure ≈ 20 (stop investing). Don't set them to zero — downstream agents use non-zero values to decide bench vs. drop.

7. Ratio cats need the minimum-IP/PA rule. Yahoo enforces minimums for pitcher ratio cats (usually 20 IP for the week). If either roster is tracking below the minimum late in the week, the ratio cat may auto-loss. Encode this in the projection dict (stddev → 0, mean → punitive) before calling the sim, AND add +20 below_min_threshold to cat_punt_score.

8. Never re-derive upstream signals. qs_probability, sb_opportunity, obp_contribution, save_role_certainty come from mlb-player-analyzer. Read them from the signal directory; do not recompute.

9. Always pass a random_seed to the sim. Without it, two runs of this skill produce slightly different cat_reachability values, which will confuse downstream agents doing diff comparisons. Default seed: 42.

Quick Reference

Where the math lives now:

Signal	Owner	Formula
cat_position	this skill	enum from current totals (ratio-direction aware)
cat_pressure	this skill	baseline 50 + 20 × close + 15 × vol-edge − 10 × locked_win − 30 × locked_loss
cat_reachability	delegated to matchup-win-probability-sim	= round(100 × per_cat_win_probability[cat])
cat_punt_score	this skill (uses sim output)	(100 × (1 − p_cat)) × 0.6 + 30 × volatile + 20 × below_min − 10 × spillover
matchup_win_probability	delegated to matchup-win-probability-sim	Monte Carlo P(cats_won ≥ 6)

cat_pressure =
    50                                         # neutral baseline
  + 20 × (is_close_margin: deficit/lead ≤ 10% of total)
  + 15 × (opponent_volume_exhausted: we have more games left)
  - 10 × (locked_in_win)
  - 30 × (locked_in_loss)
  clamp(0, 100)

cat_reachability = round(100 × per_cat_win_probability[cat])   # from sim

cat_punt_score =
    (100 - cat_reachability) × 0.6                      # base: if we can't reach, consider punting
  + 30 × (cat is traditionally volatile: SV)
  + 20 × (below min-PA/IP threshold)
  - 10 × (cat has spillover: K→QS, OBP→R, HR→R+RBI)
  clamp(0, 100)

League constants (from context/league-config.md):

• 10 cats: R, HR, RBI, SB, OBP, K, ERA, WHIP, QS, SV
• Inverse cats: ERA, WHIP (lower-is-better — passed as cat_inverse_list to the sim)
• OBP (not AVG) — walks matter
• QS (not W) — 6+ IP with ≤3 ER
• H2H Cats, goal = win 6+ of 10 each week (cat_win_threshold = 6)
• Daily lineup lock; weekly matchup rolls Mon-Sun

Signal file output schema (from context/frameworks/signal-framework.md):

---
type: cat-state
date: YYYY-MM-DD
emitted_by: mlb-category-state-analyzer
week: N
matchup_opponent: <team name>
scoring_days_remaining: N
matchup_win_probability: 0.58          # from matchup-win-probability-sim
expected_cats_won: 5.18                # from matchup-win-probability-sim
sim_meta:
  sim_mode: monte_carlo
  n_simulations: 10000
  random_seed: 42
synthesis_confidence: 0.0-1.0
source_urls:
  - https://baseball.fantasysports.yahoo.com/b1/23756/5/matchup?week=N
---

Body: per-cat table + overall push/maintain/punt recommendation + red-team findings.

Thresholds used downstream:

Agent	Threshold	Effect
Waiver analyst	cat_pressure ≥ 60	Prioritize targets that fill that cat
Streaming strategist	cat_pressure (ERA/WHIP) < 30	Allow riskier streamers (we're punting)
Lineup optimizer	matchup_win_probability < 0.4 / > 0.6	Variance-seek as underdog / damp as favorite
Trade analyzer	weights trade_cat_delta	Multiplied by cat_pressure / 50

Key resources:

• resources/template.md: Output signal file format, per-cat table, sim-integration worked example
• resources/methodology.md: Yahoo scrape procedure, remaining-games projection, building per-cat projection dicts, sim-integration formulas
• resources/evaluators/rubric_mlb_category_state_analyzer.json: Evaluator rubric
• Sibling skill: matchup-win-probability-sim — owns per-cat and matchup-level win-probability math via Monte Carlo / Poisson-binomial

Inputs required:

• Current matchup scores (10 cats, both teams, with volume for ratio cats)
• Roster IDs for both teams
• Remaining MLB schedule through Sunday
• Upstream signals: qs_probability, save_role_certainty, obp_contribution, sb_opportunity, daily_quality
• League config (cats list, min-IP/PA thresholds, cat_win_threshold)

Outputs produced:

• signals/YYYY-MM-DD-cat-state.md — signal file with 10-cat table, overall plan, matchup_win_probability, confidence, source URLs
• cat_position, cat_pressure, cat_reachability, cat_punt_score per cat
• Overall "push N, maintain M, punt P" recommendation (N + M + P = 10, target N ≥ 6)
• matchup_win_probability (from sim delegate) for lineup-optimizer variance decisions