mlb-opponent-profiler

What this skill does

# MLB Opponent Profiler

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

## Example

**Scenario**: Monday morning of Week 5. Refresh profile for `Springfield Isotopes` (manager Nikolay) after observing another high-activity week (7 moves, $14 spent on adds, 4-1 matchup win).

**Inputs**:
```yaml
team_name: "Springfield Isotopes"
yahoo_session: <authenticated chrome context>
prior_profile:                       # from context/opponents/springfield-isotopes.md (Week 4)
  archetype: balanced
  archetype_confidence: 0.50
  posterior: {balanced: 0.42, stars_and_scrubs: 0.18, punt_sv: 0.02, punt_sb: 0.04,
              punt_wins_qs: 0.03, hitter_heavy: 0.12, pitcher_heavy: 0.08,
              inactive: 0.00, frustrated_active: 0.11, unknown: 0.00}
```

**Step 1 -- Yahoo scrape (4 pages)**: teams index, team page for `team_id=8`, draftresults, transactions filtered by `tid=8`. URLs in [methodology.md](resources/methodology.md#yahoo-scrape-flow).

**Step 2 -- MLB feature extraction** yields:
```yaml
sp_roster_share: 0.35; closer_count: 2; sb_speed_count: 4; power_bat_count: 6
moves_per_week: 3.3; faab_spent_pct: 0.32; faab_avg_bid: 2.5
lineup_set_daily: true; trade_offers_sent: 1; trade_offers_received: 0
record_last_2_weeks: "8-2-0"; days_since_last_login: 0
```

**Step 3 -- Invoke `opponent-archetype-classifier`**:
```yaml
archetype_taxonomy:            # see resources/template.md -- 10 archetypes
  balanced: {...}
  stars_and_scrubs: {...}
  ...
observed_features: <from step 2>
archetype_prior: <prior_profile.posterior>     # sequential: last week's posterior is this week's prior
observation_weight: 0.65        # Week 5 -- see methodology.md observation_weight_calibration
correlated_feature_pairs:
  - [moves_per_week, faab_spent_pct]            # active managers do both
  - [sp_roster_share, closer_count]             # they trade off
```

**Step 4 -- Classifier returns**:
```yaml
posterior:
  balanced:            0.58    # up from 0.42 -- evidence accumulating
  stars_and_scrubs:    0.12
  hitter_heavy:        0.10
  frustrated_active:   0.08    # record is winning, so frustrated_active down
  pitcher_heavy:       0.07
  punt_sb:             0.03
  punt_sv:             0.01
  punt_wins_qs:        0.01
  inactive:            0.00
  unknown:             0.00

map_archetype: balanced
classification_confidence: 37.7      # 0.58 * 0.65 * 100 -- still just under 40
best_response_hints:
  - "Match cat-for-cat; decided on execution"
  - "Include in N-estimate for every common-value FAAB target"
  - "Active manager -- probe for fair consolidation trades"
```

**Step 5 -- Read existing `context/opponents/springfield-isotopes.md`, preserve manual notes, update machine-generated sections**:

The "Summary", "Apparent weaknesses", "Best response" and "Open questions" sections contain hand-authored user notes -- **keep verbatim**. Only these get refreshed:
- YAML frontmatter: `last_updated`, `confidence`, `source_urls`
- Section 2 (Archetype): archetype, archetype_confidence, archetype_evidence
- Section 3 (Category strength): cat_strength, presumed_punts, likely_pushes
- Section 4 (Behavioral): activity_level, last_active, waiver_aggression, faab_remaining, faab_avg_bid_pct, trade_propensity

**Step 6 -- Emit weekly signal** at `signals/wk05-opponent-profiles.md`:
```markdown
---
type: opponent_profile_summary
date: 2026-04-20
week: 5
emitted_by: mlb-opponent-profiler
confidence: 0.65
source_urls: [<11 team pages + transactions + teams>]
---
## Archetype shifts since Week 4
- Springfield Isotopes: balanced 0.42 -> 0.58 (confidence 0.50 -> 0.66). Nikolay continues active pattern, record confirms execution.
- Jennys Team: inactive 0.78 -> 0.84 (confidence 0.80 -> 0.85). Still zero moves. Profile hardening.
- ...9 more

## New reactivity triggers fired
- Team 7 (Kenyi) -- outbid us on Wade Miley at $14; shift `faab_avg_bid_pct` up
```

## Workflow

Copy this checklist and track progress:

```
Opponent Profiler Progress (per team, x 11 for all_opponents):
- [ ] Step 1: Resolve team identity (team_name -> team_id, manager_alias)
- [ ] Step 2: Scrape 4 Yahoo pages for this team
- [ ] Step 3: Extract MLB-specific features (9 features; see template.md)
- [ ] Step 4: Load prior_profile.posterior as archetype_prior (sequential update)
- [ ] Step 5: Invoke opponent-archetype-classifier with 10-archetype MLB taxonomy
- [ ] Step 6: Compute cat_strength (0-100 per cat) from roster composition
- [ ] Step 7: Read existing context/opponents/<slug>.md; identify manual-notes sections
- [ ] Step 8: Write updated file atomically (preserve manual notes)
- [ ] Step 9: (at end of batch) Emit signals/wkNN-opponent-profiles.md summary
```

**Step 1: Resolve team identity**

Input is either a single `team_name` (case-insensitive, fuzzy match against canonical Yahoo names) or `all_opponents: true` (iterate over team_ids 1-12, skipping user's own team_id). Map to `team_id` and `team-slug` (lowercased, hyphenated).

- [ ] If `team_name` does not match any Yahoo team, return error -- do not guess
- [ ] `team-slug` must match the filename on disk at `context/opponents/<slug>.md` (or create new file if absent)

**Step 2: Scrape 4 Yahoo pages**

Exact URL flow documented in [resources/methodology.md](resources/methodology.md#yahoo-scrape-flow). Pages needed:

- [ ] `https://baseball.fantasysports.yahoo.com/b1/23756/teams` -- manager, last-login, W-L
- [ ] `https://baseball.fantasysports.yahoo.com/b1/23756/<team_id>` -- roster + FAAB remaining
- [ ] `https://baseball.fantasysports.yahoo.com/b1/23756/<team_id>/draftresults` -- draft pick distribution
- [ ] `https://baseball.fantasysports.yahoo.com/b1/23756/transactions?tid=<team_id>` -- adds/drops/bids/trades
- [ ] Each scrape records the exact URL in `source_urls` (for citation)
- [ ] If any page returns 4xx/5xx or auth failure, degrade gracefully (see Guardrails #3)

**Step 3: Extract MLB features**

Computed from scraped pages. See [resources/methodology.md](resources/methodology.md#feature-extraction) for exact formulas.

- [ ] `sp_roster_share`, `closer_count`, `sb_speed_count`, `power_bat_count` (roster composition)
- [ ] `moves_per_week`, `faab_spent_pct`, `faab_avg_bid` (waiver activity)
- [ ] `lineup_set_daily` (bool -- any benched-but-MLB-starting players in last 7 days?)
- [ ] `trade_offers_sent`, `trade_offers_received`
- [ ] `record_last_2_weeks`, `days_since_last_login`

**Step 4: Sequential-update prior**

Read `prior_profile.posterior` (if supplied) and pass as `archetype_prior` to the classifier. This is the key sequential-Bayes move: last week's posterior becomes this week's prior.

- [ ] If no `prior_profile`, use taxonomy priors (Week 1 only)
- [ ] If `prior_profile.posterior` sums to != 1.0, normalize and flag in `assumptions_flagged`
- [ ] Observation weight rises with week number: Wk1-2 = 0.25, Wk3-4 = 0.45, Wk5-7 = 0.65, Wk8-11 = 0.80, Wk12+ = 0.90

**Step 5: Invoke `opponent-archetype-classifier`**

Pass the 10-archetype MLB taxonomy from [resources/template.md](resources/template.md#mlb-10-archetype-taxonomy) along with the observed features, prior, and observation_weight. **Do not re-implement Bayesian math in this skill.** The classifier returns `posterior`, `map_archetype`, `classification_confidence`, `best_response_hints`, `feature_contribution_breakdown`, `assumptions_flagged`.

- [ ] Pass `correlated_feature_pairs` (see Guardrails #1)
- [ ] If classifier returns `map_archetype: "inconclusive"`, write archetype as `unknown` with confidence as returned
- [ ] Do not override or reinterpret classifier output -- store it as-is

**Step 6: Compute `cat_strength` (0-100 per cat)**

Classifier returns the archetype; the 10 per-cat strength scores come from a separate roster-based estimator (this is MLB-specific and stays in this skill). Method in [resources/methodology.md](resources/methodology.md#cat-stren