strat-gameplay-webapp/.claude/TODO_AUDIT_2025-01-14.md

# TODO Audit - 2025-01-14

**Purpose**: Comprehensive assessment of all TODOs in codebase to determine resolution timing
**Scope**: All TODO/FIXME comments in Python, TypeScript, Vue files
**Context**: Post-Phase F5 (Substitutions complete), preparing for Phase F6 (Integration)

---

## Executive Summary

**Total TODOs Found**: 53 (excluding documentation/archive files)
**Recommended for Immediate Resolution**: 8 TODOs
**Recommended for Phase F6**: 7 TODOs
**Defer to Phase F7+**: 38 TODOs

**Key Insight**: Most TODOs are either already documented for future phases or blocked by missing data/features. Can resolve ~15% now with minimal effort.

---

## Category 1: Resolve Now (8 TODOs)

These can be addressed immediately with minimal effort and will improve code quality.

### 1.1 Backend Config Cleanup

**File**: `backend/app/config/base_config.py:27-28`
```python
strikes_for_out: int = Field(default=3, description="Strikes for strikeout")  # TODO: remove - unneeded
balls_for_walk: int = Field(default=4, description="Balls for walk")  # TODO: remove - unneeded
```

**Why Now**: Marked as unneeded, just remove them
**Effort**: 5 minutes
**Impact**: Code cleanup
**Action**: Delete lines 27-28 if truly unused

---

### 1.2 Refactor Manual Result Selection Method

**File**: `backend/app/config/base_config.py:41`
```python
def supports_manual_result_selection(self) -> bool:  # TODO: consider refactor: manually selecting results is default behavior with PD allowing auto-results as an option
```

**Why Now**: Naming/logic clarity issue identified
**Effort**: 15 minutes
**Impact**: Better API semantics
**Action**: Consider renaming to `supports_auto_result_selection()` and inverting logic

---

### 1.3 OutcomesNeedingHitLocation Array

**File**: `frontend-sba/components/Gameplay/ManualOutcomeEntry.vue:152`
```typescript
const outcomesNeedingHitLocation = [  // TODO: Remove unneeded outcomes
```

**Why Now**: Component is complete, should finalize this list
**Effort**: 10 minutes
**Impact**: UI polish
**Action**: Review array and remove outcomes that don't need hit location

---

### 1.4 Toast Positioning Bug

**File**: `frontend-sba/pages/demo.vue:166`
```vue
<!-- TODO: Bottom positioning has a glitch - see PHASE_F2_COMPLETE.md Known Issues -->
```

**Why Now**: Mentioned as workaround that could be fixed
**Effort**: 30 minutes
**Impact**: Better UX
**Action**: Implement proper UI store toast system (mentioned in NEXT_SESSION.md:418)

---

### 1.5 Test Placeholder Card ID

**File**: `backend/tests/integration/test_position_ratings_api.py:31`
```python
# TODO: Replace with actual card ID from PD league
```

**Why Now**: Test improvement
**Effort**: 5 minutes
**Impact**: More realistic tests
**Action**: Use actual card ID from fixtures

---

### 1.6 WebSocket Event Emission Cleanup

**File**: `backend/app/core/game_engine.py:319, 387`
```python
# TODO Week 7 Task 4: Emit WebSocket event to notify frontend
```

**Why Now**: This is stale - WebSocket handlers are complete (Phase 3E done)
**Effort**: 5 minutes
**Impact**: Remove misleading comments
**Action**: Remove these TODOs, feature is already implemented

---

### 1.7 Rare Play (RP) Logic

**Files**:
- `backend/app/core/x_check_advancement_tables.py:63`
- `backend/app/core/x_check_advancement_tables.py:462`
- `backend/app/core/x_check_advancement_tables.py:489`

```python
'RP': ...  # TODO: Actual RP logic
```

**Why Consider**: These placeholders exist in critical tables
**Effort**: 30 minutes
**Impact**: Complete X-Check implementation
**Action**: Define what RP (Rare Play) should do or confirm placeholder is acceptable for MVP

---

### 1.8 Earned Runs Calculation

**File**: `backend/alembic/versions/004_create_stat_materialized_views.py:89`
```sql
SUM(p.run) AS erun,  -- TODO: Calculate earned runs (needs error tracking)
```

**Why Consider**: Box score stats are implemented, this might be doable now
**Effort**: 1 hour
**Impact**: More accurate statistics
**Action**: Check if error tracking exists in plays table, if so, implement earned run logic

---

## Category 2: Phase F6 - Integration (7 TODOs)

These should be addressed during Phase F6 when integrating components into game page.

### 2.1 Game Page Ownership Logic

**File**: `frontend-sba/pages/games/[id].vue:248`
```typescript
// TODO: Implement actual team ownership logic
```

**Why F6**: Game page is main focus of Phase F6
**Effort**: 30 minutes
**Priority**: High - needed for proper authorization
**Action**: Use auth context to determine if user owns team

---

### 2.2 Game Creation API Call

**File**: `frontend-sba/pages/games/create.vue:180`
```typescript
// TODO Phase F6: Call API to create game
```

**Why F6**: Explicitly marked for F6
**Effort**: 1 hour
**Priority**: High - critical flow
**Action**: Wire up `POST /api/games` endpoint

---

### 2.3 Games List API Integration

**File**: `frontend-sba/pages/games/index.vue:78, 109, 121`
```typescript
<!-- TODO Phase F6: Replace with actual games list -->
// TODO Phase F6: Fetch games from API
```

**Why F6**: Explicitly marked for F6
**Effort**: 2 hours
**Priority**: High - lobby system
**Action**: Wire up `GET /api/games` endpoint with filtering

---

### 2.4 Backend Game API Endpoints

**Files**:
- `backend/app/api/routes/games.py:25` - List games
- `backend/app/api/routes/games.py:36` - Get game
- `backend/app/api/routes/games.py:47` - Create game

```python
TODO Phase 2: Implement game listing/retrieval/creation
```

**Why F6**: Frontend F6 needs these endpoints
**Effort**: 3 hours total
**Priority**: High - required for game lobby
**Action**: Implement all three endpoints together during F6

---

## Category 3: Defer to Phase F7+ (38 TODOs)

These are documented for future phases or require features not yet ready.

### 3.1 Authentication (Phase F7+)

**Files**:
- `backend/app/api/routes/auth.py:30` - Discord OAuth flow
- `backend/app/api/routes/auth.py:54` - Auth verification

**Reason**: Auth system is Phase 1 in original PRD, not needed for local testing
**When**: Phase F7 or later when deploying to production

---

### 3.2 WebSocket Authorization (Phase F7+)

**Files**: Multiple in `backend/app/websocket/handlers.py`
- Line 71: Verify user has access to game
- Line 150: Verify user is participant
- Line 248: Verify user is active batter
- Line 516: Verify substitution authorization
- Line 682: Verify substitution authorization
- Line 838: Verify substitution authorization
- Line 960: Verify lineup view access
- Line 1076: Verify fielding team manager
- Line 1174: Verify batting team manager
- Line 1258: Verify box score view access

**Reason**: All authorization TODOs - not needed until auth system is implemented
**When**: Phase F7+ with authentication
**Count**: 10 TODOs

---

### 3.3 AI Opponent (Week 9 / Future)

**File**: `backend/app/core/ai_opponent.py`
- Lines 60, 76: Defensive setup AI
- Lines 101, 117: Offensive approach AI
- Line 130: Steal decision AI
- Line 146: Bunt decision AI

**Reason**: Explicitly marked "Week 9" or "TODO Week 9"
**When**: After MVP launch, enhanced features
**Count**: 6 TODOs

---

### 3.4 Uncapped Hit Decision Trees (Phase 4+)

**Files**:
- `backend/app/core/play_resolver.py:378` - SINGLE_UNCAPPED
- `backend/app/core/play_resolver.py:428` - DOUBLE_UNCAPPED

**Reason**: Mentioned in TODO_RESOLUTION_SUMMARY.md as "defer to Phase 4"
**When**: Phase 4 or later (advanced gameplay features)
**Count**: 2 TODOs

---

### 3.5 Interactive Decision Mechanics (Phase 4+)

**Files**:
- `backend/app/core/runner_advancement.py:1037` - Interactive decision
- `backend/app/core/runner_advancement.py:1297` - Interactive decision
- `backend/app/core/runner_advancement.py:1350` - Interactive decision

**Reason**: Requires WebSocket interactive decision flow
**When**: Phase 4+ (mentioned in TODO_RESOLUTION_SUMMARY.md)
**Count**: 3 TODOs

---

### 3.6 SPD Test with Batter Speed (Phase 3E-Final)

**File**: `backend/app/core/play_resolver.py:715`
```python
# TODO: Need batter for SPD test - placeholder for now
```

**Reason**: Documented in TODO_RESOLUTION_SUMMARY.md as Phase 3E-Final task
**Status**: Actually, this is already resolved! Position ratings are integrated.
**Action**: **VERIFY** if this is actually done, if so remove TODO

---

### 3.7 Incomplete Chart Data (Future)

**Files**: Multiple in `.claude/implementation/` docs
- phase-3b-league-config-tables.md: Error charts (P, C, 1B, 2B, 3B, SS)
- phase-3d-runner-advancement.md: Various advancement tables

**Reason**: Missing source data from game rulebook
**When**: When rulebook data is digitized
**Count**: ~10 TODOs in implementation docs (not production code)

---

## Category 4: Documentation/Archive (Not Production Code)

These TODOs are in planning docs, archive files, or session notes. No action needed.

**Files**:
- `.claude/status-*.md` (old session snapshots)
- `.claude/implementation/*.md` (planning documents)
- `.claude/archive/*.md` (archived plans)
- `.claude/PHASE_*.md` (handoff documents)

**Count**: ~15 TODOs
**Action**: None - these are historical/planning documents

---

## Recommended Action Plan

### Immediate (This Session) - 2 hours

1. **Backend Config Cleanup** (5 min)
   - Remove unneeded strikes/balls fields
   - Refactor `supports_manual_result_selection()` method

2. **Code Comment Cleanup** (10 min)
   - Remove stale "Week 7 Task 4" WebSocket comments
   - Update any other outdated comments

3. **Test Improvement** (5 min)
   - Replace placeholder card ID in position ratings test

4. **Frontend Component Polish** (30 min)
   - Clean up `outcomesNeedingHitLocation` array
   - Fix toast positioning bug if time permits

5. **Verify Resolved TODOs** (20 min)
   - Check if SPD test TODO is actually resolved (position ratings integrated)
   - Check if defender lookup TODO is actually resolved
   - Remove any TODOs that are already done

6. **Rare Play Logic** (30 min)
   - Define RP behavior or document why placeholders are OK for MVP

7. **Earned Runs Calculation** (1 hour)
   - Implement if error tracking data is available
   - Otherwise document what's needed

### Phase F6 (Next Sprint) - 6 hours

8. **Game Page Integration TODOs**
   - Implement team ownership logic
   - Wire up game creation API
   - Wire up games list API
   - Implement backend game API endpoints

### Phase F7+ (Future)

9. **Authentication** (all auth-related TODOs)
10. **AI Opponent** (all AI-related TODOs)
11. **Advanced Gameplay** (uncapped hits, interactive decisions)
12. **Data Population** (error charts, advancement tables)

---

## Summary by File Type

### Backend Python Files: 31 TODOs
- **Now**: 6 (config cleanup, test improvements, stale comments)
- **F6**: 3 (game API endpoints)
- **F7+**: 22 (auth, AI, advanced features)

### Frontend TypeScript/Vue Files: 7 TODOs
- **Now**: 2 (component cleanup, toast positioning)
- **F6**: 4 (game page, lobby)
- **F7+**: 1 (none in production code)

### Documentation Files: ~15 TODOs
- **Action**: None needed (historical/planning)

---

## Risk Assessment

### Low Risk (Safe to resolve now)
- Config cleanup
- Test improvements
- Stale comment removal
- Component polish

### Medium Risk (Need testing)
- Toast positioning fix
- Earned runs calculation
- RP logic definition

### High Risk (Defer to proper phase)
- All authentication TODOs
- Game API endpoints (should be done with F6 integration)
- Advanced gameplay features

---

## Next Steps

1. **Review this document with Cal** - Confirm priorities
2. **Execute "Immediate" section** - ~2 hours of cleanup
3. **Update TODO_RESOLUTION_SUMMARY.md** - Document what was resolved
4. **Commit cleanup** - "CLAUDE: Resolve 8 low-hanging TODOs from audit"
5. **Proceed with Phase F6** - Address F6 TODOs during integration

---

**Document Version**: 1.0
**Date**: 2025-01-14
**Contributors**: Claude (Jarvis)
**Status**: Ready for review