major-domo-v2/commands/draft/CLAUDE.md

Draft Commands

This directory contains Discord slash commands for draft system operations.

🚨 Important: Draft Period Restriction

Interactive draft commands are restricted to the offseason (week ≤ 0).

Restricted Commands

The following commands can only be used during the offseason (when league week ≤ 0):

• /draft - Make draft picks
• /draft-list - View auto-draft queue
• /draft-list-add - Add player to queue
• /draft-list-remove - Remove player from queue
• /draft-list-clear - Clear entire queue

Implementation: The @requires_draft_period decorator automatically checks the current league week and returns an error message if the league is in-season.

Unrestricted Commands

These commands remain available year-round:

• /draft-board - View draft picks by round
• /draft-status - View current draft state
• /draft-on-clock - View detailed on-the-clock information
• All /draft-admin commands (administrator only)

User Experience

When a user tries to run a restricted command during the season, they see:

❌ Not Available
Draft commands are only available in the offseason.

Files

picks.py

• Command: /draft
• Description: Make a draft pick with FA player autocomplete
• Restriction: Offseason only (week ≤ 0) via @requires_draft_period decorator
• Parameters:
  • player (required): Player name to draft (autocomplete shows FA players with position and sWAR)
• Service Dependencies:
  • draft_service.get_draft_data()
  • draft_pick_service.get_pick()
  • draft_pick_service.update_pick_selection()
  • team_service.get_team_by_owner() (CACHED)
  • team_service.get_team_roster()
  • player_service.get_players_by_name()
  • player_service.update_player_team()
  • league_service.get_current_state() (for period check)
  • draft_sheet_service.write_pick() (Google Sheets integration)

Key Features

Skipped Pick Support

• Purpose: Allow teams to make up picks they missed when not on the clock
• Detection: Checks for picks with overall < current_overall and player_id = None
• Behavior: If team is not on the clock but has skipped picks, allows drafting with earliest skipped pick
• User Experience: Success message includes footer noting this is a "skipped pick makeup"
• Draft Advancement: Does NOT advance the draft when using a skipped pick

# Skipped pick detection flow
if current_pick.owner.id != team.id:
    skipped_picks = await draft_pick_service.get_skipped_picks_for_team(
        season, team.id, current_overall
    )
    if skipped_picks:
        pick_to_use = skipped_picks[0]  # Earliest skipped pick
    else:
        # Return "Not Your Turn" error

Global Pick Lock

• Purpose: Prevent concurrent draft picks that could cause race conditions
• Implementation: asyncio.Lock() stored in cog instance
• Location: Local only (not in database)
• Timeout: 30-second stale lock auto-override
• Integration: Background monitor task respects same lock

# In DraftPicksCog
self.pick_lock = asyncio.Lock()
self.lock_acquired_at: Optional[datetime] = None
self.lock_acquired_by: Optional[int] = None

# Lock acquisition with timeout check
if self.pick_lock.locked():
    if time_held > 30:
        # Override stale lock
        pass
    else:
        # Reject with wait time
        return

async with self.pick_lock:
    # Process pick
    pass

Pick Validation Flow

1. Lock Check: Verify no active pick in progress (or stale lock >30s)
2. GM Validation: Verify user is team owner (cached lookup - fast!)
3. Draft State: Get current draft configuration
4. Turn Validation: Verify user's team is on the clock
5. Player Validation: Verify player is FA (team_id = 498)
6. Cap Space: Validate 32 sWAR limit won't be exceeded
7. Execution: Update pick, update player team, advance draft
8. Sheet Write: Write pick to Google Sheets (fire-and-forget)
9. Announcements: Post success message and player card

FA Player Autocomplete

The autocomplete function filters to FA players only:

async def fa_player_autocomplete(interaction, current: str):
    # Search all players
    players = await player_service.search_players(current, limit=25)

    # Filter to FA only (team_id = 498)
    fa_players = [p for p in players if p.team_id == 498]

    # Return choices with position and sWAR
    return [Choice(name=f"{p.name} ({p.pos}) - {p.wara:.2f} sWAR", value=p.name)]

Cap Space Validation

Uses utils.draft_helpers.validate_cap_space():

async def validate_cap_space(roster: dict, new_player_wara: float):
    # Calculate how many players count (top 26 of 32 roster spots)
    max_counted = min(26, 26 - (32 - projected_roster_size))

    # Sort all players + new player by sWAR descending
    sorted_wara = sorted(all_players_wara, reverse=True)

    # Sum top N
    projected_total = sum(sorted_wara[:max_counted])

    # Check against limit (with tiny float tolerance)
    return projected_total <= 32.00001, projected_total

Google Sheets Integration

Overview

Draft picks are automatically written to a shared Google Sheet for easy tracking. This feature:

• Writes pick data to configured sheet after each successful pick
• Uses fire-and-forget pattern (non-blocking, doesn't fail the pick)
• Supports manual resync via /draft-admin resync-sheet
• Shows sheet link in /draft-status embed

Sheet Structure

Each pick writes 4 columns starting at column D:

Column	Content
D	Original owner abbreviation
E	Current owner abbreviation
F	Player name
G	Player sWAR

Row calculation: overall + 1 (pick 1 → row 2, leaving row 1 for headers)

Fire-and-Forget Pattern

# After successful pick execution
try:
    sheet_success = await draft_sheet_service.write_pick(
        season=config.sba_season,
        overall=pick.overall,
        orig_owner_abbrev=original_owner.abbrev,
        owner_abbrev=team.abbrev,
        player_name=player.name,
        swar=player.wara
    )
    if not sheet_success:
        self.logger.warning(f"Draft sheet write failed for pick #{pick.overall}")
        # Post notification to ping channel
except Exception as e:
    self.logger.error(f"Draft sheet write error: {e}")
    # Non-critical - don't fail the draft pick

Configuration

Environment variables (optional, defaults in config):

• DRAFT_SHEET_KEY_12 - Sheet ID for season 12
• DRAFT_SHEET_KEY_13 - Sheet ID for season 13
• DRAFT_SHEET_ENABLED - Feature flag (default: True)

Config file defaults in config.py:

draft_sheet_keys: dict[int, str] = {
    12: "1OF-sAFykebc_2BrcYCgxCR-4rJo0GaNmTstagV-PMBU",
    # Add new seasons as needed
}
draft_sheet_worksheet: str = "Ordered List"
draft_sheet_start_column: str = "D"
draft_sheet_enabled: bool = True

/draft-admin resync-sheet Command

Bulk resync all picks from database to sheet:

1. Fetches all picks for current season with player data
2. Clears existing sheet data (columns D-G, rows 2+)
3. Batch writes all completed picks
4. Reports success/failure count

Use cases:

• Sheet corruption recovery
• Credential issues during draft
• Manual corrections needed

/draft-status Sheet Link

The draft status embed includes a clickable link to the sheet:

sheet_url = config.get_draft_sheet_url(config.sba_season)
embed = await create_draft_status_embed(draft_data, current_pick, lock_status, sheet_url)

Service Dependencies

• services.draft_sheet_service - Google Sheets operations
• config.get_draft_sheet_key() - Sheet ID lookup by season
• config.get_draft_sheet_url() - Sheet URL generation

Failure Handling

• Sheet write failures don't block draft picks
• Failures logged with warning level
• Optional: Post failure notice to ping channel
• Admins can use resync-sheet for recovery

Architecture Notes

Command Pattern

• Uses @logged_command("/draft") decorator (no manual error handling)
• Always defers response: await interaction.response.defer()
• Service layer only (no direct API client access)
• Comprehensive logging with contextual information

Race Condition Prevention

The global lock ensures:

• Only ONE pick can be processed at a time league-wide
• Co-GMs cannot both draft simultaneously
• Background auto-draft respects same lock
• Stale locks (crashes/network issues) auto-clear after 30s

Performance Optimizations

• Team lookup cached (get_team_by_owner uses @cached_single_item)
• 80% reduction in API calls for GM validation
• Sub-millisecond cache hits vs 50-200ms API calls
• Draft data NOT cached (changes too frequently)

Troubleshooting

Common Issues

1. "Pick In Progress" message:

   • Another user is currently making a pick
   • Wait ~30 seconds for pick to complete
   • If stuck, lock will auto-clear after 30s

2. "Not Your Turn" message:

   • Current pick belongs to different team
   • Wait for your turn in draft order
   • Admin can use /draft-admin to adjust

3. "Cap Space Exceeded" message:

   • Drafting player would exceed 32.00 sWAR limit
   • Only top 26 players count toward cap
   • Choose player with lower sWAR value

4. "Player Not Available" message:

   • Player is not a free agent
   • May have been drafted by another team
   • Check draft board for available players

Lock State Debugging

Check lock status with admin tools:

# Lock state
draft_picks_cog.pick_lock.locked()  # True if held
draft_picks_cog.lock_acquired_at  # When lock was acquired
draft_picks_cog.lock_acquired_by  # User ID holding lock

Admin can force-clear locks:

• Use /draft-admin clear-lock (when implemented)
• Restart bot (lock is local only)

Draft Format

Hybrid Linear + Snake

• Rounds 1-10: Linear draft (same order every round)
• Rounds 11+: Snake draft (reverse on even rounds)
• Special Rule: Round 11 Pick 1 = same team as Round 10 Pick 16

Pick Order Calculation

Uses utils.draft_helpers.calculate_pick_details():

def calculate_pick_details(overall: int) -> tuple[int, int]:
    round_num = math.ceil(overall / 16)

    if round_num <= 10:
        # Linear: 1-16, 1-16, 1-16, ...
        position = ((overall - 1) % 16) + 1
    else:
        # Snake: odd rounds forward, even rounds reverse
        if round_num % 2 == 1:
            position = ((overall - 1) % 16) + 1
        else:
            position = 16 - ((overall - 1) % 16)

    return round_num, position

Integration with Background Task

The draft monitor task (tasks/draft_monitor.py) integrates with this command:

1. Shared Lock: Monitor acquires same pick_lock for auto-draft
2. Timer Expiry: When deadline passes, monitor auto-drafts
3. Draft List: Monitor tries players from team's draft list in order
4. Pick Advancement: Monitor calls same draft_service.advance_pick()

Implemented Commands

/draft-status

Display current draft state, timer, lock status

/draft-admin (Administrator Only)

Admin controls:

• /draft-admin timer - Enable/disable timer (auto-starts monitor task)
• /draft-admin set-pick - Set current pick (auto-starts monitor if timer active)
• /draft-admin channels - Configure ping/result channels
• /draft-admin wipe - Clear all picks for season
• /draft-admin info - View detailed draft configuration
• /draft-admin resync-sheet - Resync all picks to Google Sheet

/draft-list

View auto-draft queue for your team

/draft-list-add

Add player to auto-draft queue

/draft-list-remove

Remove player from auto-draft queue

/draft-list-clear

Clear entire auto-draft queue

/draft-board

View draft board by round with pagination

/draft-on-clock

View detailed on-the-clock information including:

• Current team on the clock
• Deadline with relative timestamp
• Team's current sWAR and cap space
• Last 5 picks
• Top 5 roster players by sWAR

Dependencies

• config.get_config()
• services.draft_service
• services.draft_pick_service
• services.draft_sheet_service (Google Sheets integration)
• services.player_service
• services.team_service (with caching)
• utils.decorators.logged_command
• utils.draft_helpers.validate_cap_space
• views.draft_views.*
• asyncio.Lock for race condition prevention

Testing

Run tests with: python -m pytest tests/test_commands_draft.py -v (when implemented)

Test scenarios:

• Concurrent picks: Two users try to draft simultaneously
• Stale lock: Lock held >30s gets overridden
• Cap validation: Player would exceed 32 sWAR limit
• Turn validation: User tries to draft out of turn
• Player availability: Player already drafted

Security Considerations

Permission Validation

• Only team owners (GMs) can make draft picks
• Validated via team_service.get_team_by_owner()
• Cached for performance (30-minute TTL)

Data Integrity

• Global lock prevents duplicate picks
• Cap validation prevents roster violations
• Turn validation enforces draft order
• All updates atomic (pick + player team)

Database Requirements

• Draft data table (configuration and state)
• Draft picks table (all picks for season)
• Draft list table (auto-draft queues)
• Player records with team associations
• Team records with owner associations

---

Last Updated: December 2025 Status: All draft commands implemented and tested Recent: Google Sheets integration for automatic pick tracking, /draft-admin resync-sheet command, sheet link in /draft-status