Sportstime/.planning/phases/03-alias-systems/03-01-PLAN.md

phase, plan, type

phase	plan	type
03-alias-systems	01	execute

Add NFL to the canonicalization pipeline with complete alias support.

Purpose: NFL is a core sport but missing from team/game canonicalization, breaking game→team→stadium linking for NFL games. Output: NFL teams canonicalized with division structure, NFL abbreviation aliases for game resolution, NFL stadium historical aliases.

<execution_context> ~/.claude/get-shit-done/workflows/execute-phase.md ~/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/phases/01-script-architecture/01-03-SUMMARY.md

Key source files:

@Scripts/canonicalize_teams.py @Scripts/canonicalize_games.py @Scripts/canonicalize_stadiums.py @Scripts/nfl.py

Prior decisions:

• NFL uses cross-calendar-year season format (2025-26) like NBA/NHL
• Each sport module exports {SPORT}_TEAMS dict with team mappings
• canonicalize_teams.py uses division mappings for conference/division assignment

Patterns established:

• Team canonicalization: import {SPORT}_TEAMS, add {SPORT}_DIVISIONS dict, include in sport_mappings list
• Game resolution: TEAM_ABBREV_ALIASES dict maps alternate abbrevs to canonical team IDs
• Stadium aliases: HISTORICAL_STADIUM_ALIASES dict maps canonical_id to list of historical names with dates

Task 1: Add NFL to canonicalize_teams.py Scripts/canonicalize_teams.py 1. Add NFL_TEAMS to import statement: `from scrape_schedules import NBA_TEAMS, MLB_TEAMS, NHL_TEAMS, NFL_TEAMS` 2. Add NFL_DIVISIONS dict with all 32 teams mapped to (conference_id, division_id): - AFC East: BUF, MIA, NE, NYJ → ('nfl_afc', 'nfl_afc_east') - AFC North: BAL, CIN, CLE, PIT → ('nfl_afc', 'nfl_afc_north') - AFC South: HOU, IND, JAX, TEN → ('nfl_afc', 'nfl_afc_south') - AFC West: DEN, KC, LV, LAC → ('nfl_afc', 'nfl_afc_west') - NFC East: DAL, NYG, PHI, WAS → ('nfl_nfc', 'nfl_nfc_east') - NFC North: CHI, DET, GB, MIN → ('nfl_nfc', 'nfl_nfc_north') - NFC South: ATL, CAR, NO, TB → ('nfl_nfc', 'nfl_nfc_south') - NFC West: ARI, LAR, SF, SEA → ('nfl_nfc', 'nfl_nfc_west') 3. Add ('NFL', NFL_TEAMS) to sport_mappings list in canonicalize_all_teams() 4. Update canonicalize_teams() to use 'stadium' key for NFL (same as MLB, not 'arena') 5. Add NFL_DIVISIONS to division_map dict

Note: NFL_TEAMS uses 'stadium' key (not 'arena' like NBA/NHL), so the arena_key logic already handles this.

python Scripts/canonicalize_teams.py --verbose 2>&1 | grep -E "NFL:|Created.*teams" NFL teams appear in output with 32 teams, no warnings about stadium matches Task 2: Add NFL team abbreviation aliases to canonicalize_games.py Scripts/canonicalize_games.py Add NFL entries to TEAM_ABBREV_ALIASES dict for common abbreviation variations:

```python
# NFL
('NFL', 'JAC'): 'team_nfl_jax',   # Jacksonville (JAC vs JAX)
('NFL', 'OAK'): 'team_nfl_lv',    # Oakland → Las Vegas Raiders (moved 2020)
('NFL', 'SD'): 'team_nfl_lac',    # San Diego → Los Angeles Chargers (moved 2017)
('NFL', 'STL'): 'team_nfl_lar',   # St. Louis → Los Angeles Rams (moved 2016)
('NFL', 'GNB'): 'team_nfl_gb',    # Green Bay alternate
('NFL', 'KAN'): 'team_nfl_kc',    # Kansas City alternate
('NFL', 'NWE'): 'team_nfl_ne',    # New England alternate
('NFL', 'NOR'): 'team_nfl_no',    # New Orleans alternate
('NFL', 'TAM'): 'team_nfl_tb',    # Tampa Bay alternate
('NFL', 'SFO'): 'team_nfl_sf',    # San Francisco alternate
('NFL', 'WAS'): 'team_nfl_was',   # Washington (direct match but include for completeness)
```

These cover:
- Historical relocations (OAK→LV, SD→LAC, STL→LAR)
- Common 3-letter variations used by different data sources

grep -c "NFL" Scripts/canonicalize_games.py | head -1 NFL aliases present in TEAM_ABBREV_ALIASES dict (should show 10+ NFL entries) Task 3: Add NFL stadium historical aliases to canonicalize_stadiums.py Scripts/canonicalize_stadiums.py Add NFL entries to HISTORICAL_STADIUM_ALIASES dict for sponsorship changes and renames:

```python
# NFL
'stadium_nfl_sofi_stadium': [
    # SoFi Stadium opened 2020, no prior name
],
'stadium_nfl_allegiant_stadium': [
    # Allegiant Stadium opened 2020, no prior name (Raiders moved from Oakland Coliseum)
],
'stadium_nfl_caesars_superdome': [
    {'alias_name': 'mercedes-benz superdome', 'valid_from': '2011-10-01', 'valid_until': '2021-07-01'},
    {'alias_name': 'louisiana superdome', 'valid_from': '1975-08-01', 'valid_until': '2011-09-30'},
    {'alias_name': 'superdome', 'valid_from': '1975-08-01'},
],
'stadium_nfl_paycor_stadium': [
    {'alias_name': 'paul brown stadium', 'valid_from': '2000-08-01', 'valid_until': '2022-09-05'},
],
'stadium_nfl_empower_field_at_mile_high': [
    {'alias_name': 'broncos stadium at mile high', 'valid_from': '2018-09-01', 'valid_until': '2019-08-31'},
    {'alias_name': 'sports authority field at mile high', 'valid_from': '2011-08-01', 'valid_until': '2018-08-31'},
    {'alias_name': 'invesco field at mile high', 'valid_from': '2001-09-01', 'valid_until': '2011-07-31'},
    {'alias_name': 'mile high stadium', 'valid_from': '1960-01-01', 'valid_until': '2001-08-31'},
],
'stadium_nfl_acrisure_stadium': [
    {'alias_name': 'heinz field', 'valid_from': '2001-08-01', 'valid_until': '2022-07-10'},
],
'stadium_nfl_everbank_stadium': [
    {'alias_name': 'tiaa bank field', 'valid_from': '2018-01-01', 'valid_until': '2023-03-31'},
    {'alias_name': 'everbank field', 'valid_from': '2014-01-01', 'valid_until': '2017-12-31'},
    {'alias_name': 'alltel stadium', 'valid_from': '1997-06-01', 'valid_until': '2006-12-31'},
    {'alias_name': 'jacksonville municipal stadium', 'valid_from': '1995-08-01', 'valid_until': '1997-05-31'},
],
'stadium_nfl_northwest_stadium': [
    {'alias_name': 'fedexfield', 'valid_from': '1999-11-01', 'valid_until': '2025-01-01'},
    {'alias_name': 'fedex field', 'valid_from': '1999-11-01', 'valid_until': '2025-01-01'},
    {'alias_name': 'jack kent cooke stadium', 'valid_from': '1997-09-01', 'valid_until': '1999-10-31'},
],
'stadium_nfl_hard_rock_stadium': [
    {'alias_name': 'sun life stadium', 'valid_from': '2010-01-01', 'valid_until': '2016-07-31'},
    {'alias_name': 'land shark stadium', 'valid_from': '2009-01-01', 'valid_until': '2009-12-31'},
    {'alias_name': 'dolphin stadium', 'valid_from': '2005-01-01', 'valid_until': '2008-12-31'},
    {'alias_name': 'pro player stadium', 'valid_from': '1996-04-01', 'valid_until': '2004-12-31'},
    {'alias_name': 'joe robbie stadium', 'valid_from': '1987-08-01', 'valid_until': '1996-03-31'},
],
'stadium_nfl_highmark_stadium': [
    {'alias_name': 'bills stadium', 'valid_from': '2020-03-01', 'valid_until': '2021-03-31'},
    {'alias_name': 'new era field', 'valid_from': '2016-08-01', 'valid_until': '2020-02-29'},
    {'alias_name': 'ralph wilson stadium', 'valid_from': '1998-08-01', 'valid_until': '2016-07-31'},
    {'alias_name': 'rich stadium', 'valid_from': '1973-08-01', 'valid_until': '1998-07-31'},
],
'stadium_nfl_geha_field_at_arrowhead_stadium': [
    {'alias_name': 'arrowhead stadium', 'valid_from': '1972-08-01'},
],
'stadium_nfl_att_stadium': [
    {'alias_name': 'cowboys stadium', 'valid_from': '2009-05-01', 'valid_until': '2013-07-24'},
],
'stadium_nfl_us_bank_stadium': [
    # Opened 2016, no prior name (Vikings moved from Metrodome)
],
'stadium_nfl_lumen_field': [
    {'alias_name': 'centurylink field', 'valid_from': '2011-06-01', 'valid_until': '2020-11-18'},
    {'alias_name': 'qwest field', 'valid_from': '2004-06-01', 'valid_until': '2011-05-31'},
    {'alias_name': 'seahawks stadium', 'valid_from': '2002-07-01', 'valid_until': '2004-05-31'},
],
```

Only include stadiums with actual historical name changes. Skip stadiums like Soldier Field, Lambeau Field that have kept their names.

grep -c "stadium_nfl" Scripts/canonicalize_stadiums.py NFL stadium aliases present in HISTORICAL_STADIUM_ALIASES (should show 10+ entries) Before declaring plan complete: - [ ] `python Scripts/canonicalize_teams.py --verbose` shows 32 NFL teams with stadium matches - [ ] `python Scripts/canonicalize_stadiums.py --verbose` runs without error - [ ] NFL entries exist in all three canonicalization scripts

<success_criteria>

• All tasks completed
• NFL teams appear in teams_canonical.json output
• NFL stadium aliases added to canonicalization
• NFL abbreviation variations covered for game resolution </success_criteria>

After completion, create `.planning/phases/03-alias-systems/03-01-SUMMARY.md`