---
phase: 03-alias-systems
plan: 01
type: 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.
~/.claude/get-shit-done/workflows/execute-phase.md
~/.claude/get-shit-done/templates/summary.md
@.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
- All tasks completed
- NFL teams appear in teams_canonical.json output
- NFL stadium aliases added to canonicalization
- NFL abbreviation variations covered for game resolution