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

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

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

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

<!-- 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

# 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

# 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

'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

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

// 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

// 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

<!-- 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

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

# 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