strat-gameplay-webapp/.claude/implementation/TODO_RESOLUTION_SUMMARY.md

TODO Resolution Summary

Date: 2025-11-02 Session: Post-Phase 3D cleanup

TODOs Resolved

✅ TODO #1: X-Check Runner Advancement Integration (RESOLVED)

Location: backend/app/core/play_resolver.py:717

Original TODO:

# TODO: Will use _get_x_check_advancement when advancement tables are ready

Resolution:

• Status: ✅ COMPLETE
• Implementation: Added _get_x_check_advancement() method that routes to appropriate functions
• Files Modified:
  • backend/app/core/play_resolver.py (+210 lines)
  • backend/tests/unit/core/test_runner_advancement.py (fixed test expectation)

What Was Implemented:

1. Main routing method: _get_x_check_advancement()

   • Routes G1, G2, G3 → x_check_g1/2/3() (Phase 3D tables)
   • Routes F1, F2, F3 → x_check_f1/2/3() (Phase 3D tables)
   • Routes SI1, SI2, DO2, DO3, TR3 → New helper with error bonuses
   • Routes FO, PO → New helper for error-overridden outs

2. Hit advancement helper: _get_hit_advancement_with_error()

   • Reuses existing _advance_on_single_1/2(), _advance_on_double_2/3(), _advance_on_triple()
   • Adds error bonuses: E1 = +1 base, E2 = +2 bases, E3 = +3 bases, RP = +3 bases
   • Caps advancement at home (base 4)

3. Out advancement helper: _get_out_advancement_with_error()

   • When out + error: error prevents out, all runners advance by error amount
   • When out + no error: just record the out

4. New helper: _advance_on_triple()

   • All runners score on triple
   • Extracted from resolve_outcome() for reuse

Test Results:

• ✅ All 9 PlayResolver tests passing
• ✅ All 59 X-Check advancement tests passing
• ✅ All 9 X-Check placeholder tests passing
• Total: 77 tests covering X-Check integration

---

TODOs for Phase 3E (WebSocket/UI Integration)

🔲 TODO #2: Defender Lookup from Lineup

Location: backend/app/core/play_resolver.py:626

Current Code:

# TODO: Need to get defender from lineup based on position
defender_range = 3  # Placeholder
defender_error_rating = 10  # Placeholder
defender_id = 0  # Placeholder

Requirements:

1. Fetch active lineup from state or state_manager cache
2. Find player at check_position (SS, LF, 3B, etc.)
3. Look up PositionRating for that player at that position
4. Use rating.range and rating.error in X-Check resolution

Implementation Plan (Phase 3E Task 4):

• Add PositionRatingService integration to PlayResolver
• Update _resolve_x_check() to call position_service.get_rating()
• Handle missing ratings gracefully (use league defaults)
• SBA league: may not have ratings (use default values)

Estimated Effort: 1 hour

---

🔲 TODO #3: SPD Test with Batter Speed

Location: backend/app/core/play_resolver.py:667

Current Code:

# TODO: Need batter for SPD test - placeholder for now
converted_result = 'G3'  # Default to G3 if SPD test fails

Requirements:

1. Get batter's speed rating from player model
2. Roll 1d20 and compare to speed (1-20 scale)
3. If roll ≤ speed: SPD test passes → result stays 'SPD' or converts to success
4. If roll > speed: SPD test fails → converts to 'G3' (slow runner caught)

Implementation Plan (Phase 3E):

• Add speed field to PositionRating model (or separate attribute)
• Update _resolve_x_check() to get batter speed
• Implement actual SPD test logic (currently defaults to fail)
• Log SPD test results in XCheckResult

Estimated Effort: 30 minutes

---

TODOs for Phase 4+ (Future Features)

🔴 TODO #4-7: Deferred to Phase 4

Uncapped Hit Decision Trees (play_resolver.py:373, 423):

• SINGLE_UNCAPPED and DOUBLE_UNCAPPED need interactive decision flow
• Not critical for MVP
• Defer to Phase 4 or later

Runner Speed Modifiers (runner_advancement.py:470):

• Enhance DP probability calculations with runner speed
• Currently using base 45% probability
• Defer until player ratings fully integrated

DECIDE Interactive Mechanics (runner_advancement.py:1155, 1433, 1486):

• FLYOUT_B: R2 may attempt to tag to 3rd
• FLYOUT_BQ: R3 may attempt to score
• Groundball Result 12: Lead runner advancement attempt
• Requires WebSocket interactive decision flow
• Defer to Phase 4 (advanced gameplay features)

X-Check Flyball with GameState (runner_advancement.py:1678):

• Currently x_check_f1/f2/f3 with NO error return simplified results
• Could refactor to use GameState for proper FLYOUT_A/B/C logic
• Current implementation works; optimization can wait

---

Implementation Quality Notes

Code Reuse Achievement

Successfully reused existing code instead of duplicating logic:

• ✅ Existing _advance_on_single_1/2() methods reused
• ✅ Existing _advance_on_double_2/3() methods reused
• ✅ New _advance_on_triple() extracted for reuse
• ✅ Error bonus logic cleanly added on top of base advancement
• ✅ No code duplication between X-Check and standard plays

Test Coverage

• All existing tests still passing
• Fixed 1 test bug (wrong on_base_code expectation)
• X-Check integration fully tested through existing test suites
• No new test files needed (used existing test coverage)

Documentation

Files updated with detailed docstrings:

• _get_x_check_advancement(): Complete routing logic documented
• _get_hit_advancement_with_error(): Error bonus rules documented
• _get_out_advancement_with_error(): Out override logic documented

---

Next Steps

1. Document Phase 3E TODOs in NEXT_SESSION.md ✅ (already done)

2. Commit this implementation:

   git add backend/app/core/play_resolver.py
   git add backend/tests/unit/core/test_runner_advancement.py
   git add .claude/implementation/TODO_RESOLUTION_SUMMARY.md
   git commit -m "CLAUDE: Resolve TODO #1 - Complete X-Check advancement integration"
   

3. Begin Phase 3E when ready:

   • Create PD API client for position ratings
   • Implement Redis caching for position ratings
   • Update PlayResolver to use actual defender ratings (TODO #2)
   • Implement SPD test with batter speed (TODO #3)
   • Add WebSocket events for X-Check flows

---

Summary

Resolved: 1 TODO (but implemented much more than just a placeholder!)

• TODO #1: X-Check advancement integration
  • Scope: Originally just "use the tables when ready"
  • Delivered: Complete implementation including hits with errors and outs with errors
  • Bonus: Reused existing code, added comprehensive helpers

Documented for Phase 3E: 2 TODOs

• TODO #2: Defender lookup (Phase 3E Task 4)
• TODO #3: SPD test (Phase 3E)

Deferred to Phase 4+: 4 TODOs

• Uncapped hit decision trees
• Runner speed modifiers
• DECIDE interactive mechanics
• X-Check flyball optimization

Test Status: ✅ All 77 relevant tests passing

Ready For: Phase 3E implementation