# Team-First Planning Mode Implementation Plan

## Overview

**Feature:** Select teams (not dates), find optimal trip windows across the entire season.

**Use Case:** User has 3 stadiums left on bucket list. Select those 3 teams, app finds all windows throughout the season where all 3 teams play at home within a reasonable trip duration.

## Requirements

| Constraint | Value |
|------------|-------|
| Sport scope | Single sport per search |
| Start city | Flexible (algorithm picks optimal) |
| Max duration | `teams × 2` days (3 teams = 6 days) |
| Drive limit | Existing settings value |
| Optimize for | Shortest duration + minimal backtracking |
| Results | Top 10 options with reasoning |
| Season | Current season only |

---

## Architecture

### Current Flow (Date-First)
```
User picks dates → Fetch games in range → Find routes → Rank → Display
```

### New Flow (Team-First)
```
User picks teams → Fetch ALL home games for those teams (full season)
→ Generate sliding windows (N-day chunks)
→ Filter to windows where all teams have ≥1 home game
→ For each valid window: find optimal routes
→ Rank by duration + miles → Return top 10
```

### Reuse Ratio: ~90%

| Component | Status | Notes |
|-----------|--------|-------|
| `allGames(for sports:)` | ✅ Exists | Full season fetch |
| Sliding window generator | ✅ Exists | In ScenarioBPlanner |
| GameDAGRouter | ✅ Exists | Supports anchor constraints |
| ItineraryBuilder | ✅ Exists | No changes needed |
| Max driving time | ✅ Exists | `UserPreferences.maxDrivingHoursPerDriver` |
| Multi-team selection UI | ❌ New | Currently single-team only |
| Team-first planner | ❌ New | ~300 lines adapting Scenario B |
| Window optimization | ⚠️ Adapt | Season = 180+ days → need sampling |

---

## Parallel Track Structure

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              PHASE 1 (Parallel)                              │
├──────────────────────┬──────────────────────┬──────────────────────────────┤
│   Track A: Models    │   Track B: Planner   │   Track C: UI Components     │
│   (Agent 1)          │   (Agent 2)          │   (Agent 3)                  │
├──────────────────────┼──────────────────────┼──────────────────────────────┤
│ A1. Add teamFirst    │ B1. Create           │ C1. Create TeamPickerView    │
│     to PlanningMode  │     ScenarioEPlanner │     (multi-select grid)      │
│                      │     skeleton         │                              │
│ A2. Add              │ B2. Implement        │ C2. Create                   │
│     selectedTeamIds  │     window generator │     TeamFirstWizardStep      │
│     to TripPrefs     │     for teams        │                              │
│                      │                      │                              │
│ A3. Update           │ B3. Implement route  │ C3. Update WizardViewModel   │
│     PlanningRequest  │     finding with     │     for teamFirst mode       │
│     computed props   │     team anchors     │                              │
└──────────────────────┴──────────────────────┴──────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              PHASE 2 (Parallel)                              │
├─────────────────────────────────┬───────────────────────────────────────────┤
│   Track D: Integration          │   Track E: Tests                          │
│   (Agent 4)                     │   (Agent 5)                               │
├─────────────────────────────────┼───────────────────────────────────────────┤
│ D1. Update ScenarioPlannerFactory│ E1. Unit tests for window generator     │
│     to detect teamFirst mode    │                                           │
│                                 │ E2. Unit tests for ScenarioEPlanner       │
│ D2. Wire TeamPickerView into    │                                           │
│     existing wizard flow        │ E3. Integration test: 3 teams → routes    │
│                                 │                                           │
│ D3. Add teamFirst option to     │ E4. Edge case tests (no windows, etc.)    │
│     planning mode selector      │                                           │
└─────────────────────────────────┴───────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         PHASE 3 (Sequential)                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│ F1. End-to-end testing & bug fixes                                          │
│ F2. Performance optimization (if needed)                                     │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Detailed Task Specifications

### Track A: Data Models (Agent 1)

**A1. Add `teamFirst` to PlanningMode**
```
File: SportsTime/Core/Models/Domain/TripPreferences.swift
Action: Add case to PlanningMode enum
```

**A2. Add `selectedTeamIds` to TripPreferences**
```
File: SportsTime/Core/Models/Domain/TripPreferences.swift
Action: Add `var selectedTeamIds: Set<String> = []`
Action: Add `var teamFirstMaxDays: Int` computed as `selectedTeamIds.count * 2`
```

**A3. Update PlanningRequest computed properties**
```
File: SportsTime/Planning/Models/PlanningModels.swift
Action: Add computed property to extract teams for selected IDs
Action: Add helper to get all home games for selected teams
```

---

### Track B: Scenario Planner (Agent 2)

**B1. Create ScenarioEPlanner skeleton**
```
File: SportsTime/Planning/Scenarios/ScenarioEPlanner.swift (NEW)
Action: Create class conforming to ScenarioPlanner protocol
Action: Implement required methods with TODOs
```

**B2. Implement window generator for teams**
```
File: SportsTime/Planning/Scenarios/ScenarioEPlanner.swift
Action: Generate all N-day windows across season
Action: Filter to windows where ALL selected teams have ≥1 home game
Action: Cap at 50 windows (sample if more)
```

**B3. Implement route finding with team anchors**
```
File: SportsTime/Planning/Scenarios/ScenarioEPlanner.swift
Action: For each valid window, collect all home games for selected teams
Action: Pass to GameDAGRouter with those games as anchors
Action: Build itineraries, rank by duration + miles
Action: Return top 10
```

---

### Track C: UI Components (Agent 3)

**C1. Create TeamPickerView**
```
File: SportsTime/Features/Trip/Views/TeamPickerView.swift (NEW)
Action: Grid of team logos/names for selected sport
Action: Multi-select with checkmarks
Action: Show count badge "3 selected"
Action: Binding to Set<String> for team IDs
```

**C2. Create TeamFirstWizardStep**
```
File: SportsTime/Features/Trip/Views/Wizard/TeamFirstWizardStep.swift (NEW)
Action: Wrapper that uses TeamPickerView
Action: Validation: require ≥2 teams selected
Action: "Find trips for these teams" CTA
```

**C3. Update WizardViewModel for teamFirst mode**
```
File: SportsTime/Features/Trip/ViewModels/TripWizardViewModel.swift
Action: Add teamFirst step configuration
Action: Handle selectedTeamIds state
Action: Skip date selection step when in teamFirst mode
```

---

### Track D: Integration (Agent 4)

**D1. Update ScenarioPlannerFactory**
```
File: SportsTime/Planning/Scenarios/ScenarioPlannerFactory.swift
Action: Add detection for teamFirst mode
Action: Return ScenarioEPlanner when selectedTeamIds.count >= 2
```

**D2. Wire TeamPickerView into wizard**
```
File: SportsTime/Features/Trip/Views/Wizard/TripWizardView.swift
Action: Add case for teamFirst step
Action: Navigation flow: Sport → Teams → (skip dates) → Results
```

**D3. Add teamFirst to mode selector**
```
File: SportsTime/Features/Trip/Views/Wizard/PlanningModeSelector.swift
Action: Add "Teams First" option with icon
Action: Description: "Pick teams, we'll find the best windows"
```

---

### Track E: Tests (Agent 5)

**E1. Unit tests for window generator**
```
File: SportsTimeTests/Planning/ScenarioEPlannerTests.swift (NEW)
Tests:
- 3 teams, 6-day window → finds valid windows
- Window with only 2 of 3 teams → excluded
- Empty season → returns empty
- Sampling works when >50 windows
```

**E2. Unit tests for ScenarioEPlanner**
```
File: SportsTimeTests/Planning/ScenarioEPlannerTests.swift
Tests:
- Returns PlanningResult with routes
- All routes include all selected teams
- Routes sorted by duration ascending
- Respects max driving time constraint
```

**E3. Integration test**
```
File: SportsTimeTests/Planning/TeamFirstIntegrationTests.swift (NEW)
Tests:
- Full flow: 3 MLB teams → top 10 routes
- Each route visits all 3 stadiums
- Total duration ≤ 6 days
```

**E4. Edge case tests**
```
File: SportsTimeTests/Planning/ScenarioEPlannerTests.swift
Tests:
- Teams with no overlapping games → graceful error
- Single team selected → validation error
- Teams in same city → treated as separate stops
```

---

## Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| Season = 180+ days = too many windows | Sample every 2nd day, or limit to weekends |
| No valid windows (teams never align) | Early validation + user feedback |
| Slow computation (10+ windows × routing) | Cap at 50 windows, parallelize |
| Teams in same city (e.g., 2 NYC teams) | Treat as separate stops (different stadiums) |

---

## Test Strategy

1. **Unit:** Window generator finds correct multi-team windows
2. **Unit:** Anchor constraints include all teams' home games
3. **Integration:** 3 teams → returns routes visiting all 3
4. **Edge:** Teams with non-overlapping seasons → graceful "no trips found"
5. **Perf:** Full MLB season (2,430 games) completes in <5s

---

## Estimated Effort

| Track | New Code | Modified Code | Total |
|-------|----------|---------------|-------|
| A: Models | 50 lines | 20 lines | 70 lines |
| B: Planner | 300 lines | 0 lines | 300 lines |
| C: UI | 250 lines | 50 lines | 300 lines |
| D: Integration | 30 lines | 80 lines | 110 lines |
| E: Tests | 400 lines | 0 lines | 400 lines |
| **Total** | **1,030 lines** | **150 lines** | **1,180 lines** |
