PokeR/openspec/changes/archive/2026-05-17-bot-intelligence/tasks.md

1. Type System & Data Models

• 1.1 Define BotArchetype enum with all 8 archetypes (Nit, TAG, LAG, Maniac, CallingStation, LooseFish, OldMan, MonsterTAG)
• 1.2 Define SkillLevel enum with 5 tiers (Novice, Beginner, Medium, Hard, Ultra)
• 1.3 Extend PlayerSeat type with personality and skillLevel fields
• 1.4 Create PersonalityProfile type with VPIP range, PFR range, bluff frequency, aggression pattern, and timeout default
• 1.5 Create ObservationStats type with VPIP, PFR, FoldToCBet, WTSD, bet sizing profiles, timing data
• 1.6 Extend GameState to include observationData field mapping player IDs to ObservationStats

2. Bot Personality Profiles

• 2.1 Implement personality profile for Nit archetype (VPIP 5-15%, PFR 4-12%, low bluff, timeout: fold)
• 2.2 Implement personality profile for TAG archetype (VPIP 15-25%, PFR 10-20%, moderate bluff, timeout: check/fold)
• 2.3 Implement personality profile for LAG archetype (VPIP 25-40%, PFR 20-35%, high bluff, timeout: call)
• 2.4 Implement personality profile for Maniac archetype (VPIP 40-60%, PFR 35-55%, extreme bluff, timeout: raise)
• 2.5 Implement personality profile for Calling Station archetype (VPIP 30-50%, PFR 5-15%, zero bluff, timeout: call)
• 2.6 Implement personality profile for Loose Fish archetype (VPIP 35-50%, PFR 10-20%, low bluff, timeout: call)
• 2.7 Implement personality profile for Old Man archetype (VPIP 10-20%, PFR 3-8%, zero bluff, timeout: call)
• 2.8 Implement personality profile for Monster TAG archetype (VPIP 10-18%, PFR 9-16%, selective bluff, timeout: check)

3. Mistake Libraries

• 3.1 Define mistake library for Nit (folds too much, misses value, never bluffs)
• 3.2 Define mistake library for TAG (occasional dominated hand play, slow-plays too often)
• 3.3 Define mistake library for LAG (overbluffs river, wide EP ranges, inconsistent sizing)
• 3.4 Define mistake library for Maniac (bluffs into strength, can't extract value, zero fold ability)
• 3.5 Define mistake library for Calling Station (calls with any pair, never folds post-flop, tiny bets)
• 3.6 Define mistake library for Loose Fish (calls too wide, occasional surprise raise, small bets)
• 3.7 Define mistake library for Old Man (smooth-calls then folds, misses value checks, passive to a fault)
• 3.8 Define mistake library for Monster TAG (rarely misreads, occasionally gets trapped by extreme bluffers)
• 3.9 Implement skill-level error rate mapping (Novice ~40%, Beginner ~25%, Medium ~15%, Hard ~10%, Ultra ~5%)
• 3.10 Implement mistake injection function that samples from archetype library based on skill error rate

4. Base Strategy Engine

• 4.1 Implement position-based hand ranking chart for pre-flop decisions (9 positions × hand matrix)
• 4.2 Implement post-flop base strategy using hand strength evaluation vs board texture
• 4.3 Implement pot odds calculation for drawing hand decisions
• 4.4 Implement base bluff frequency calculator based on board and position
• 4.5 Implement base bet sizing recommendations per street

5. Bot Decision Pipeline

• 5.1 Implement three-layer pipeline: base strategy → personality filter → skill noise
• 5.2 Implement personality filter that reshapes action probabilities based on archetype profile
• 5.3 Implement skill noise layer that probabilistically overrides decisions with mistakes
• 5.4 Implement timing decision function (archetype × skill determines how long bot "thinks")
• 5.5 Integrate bot decision engine into turn.ts to replace coin-flip logic

6. Decision Timer System

• 6.1 Create Timer component with configurable duration and visual countdown display
• 6.2 Implement sequential timer management (starts for current player, advances on action/timeout)
• 6.3 Implement timeout action handler that triggers archetype-appropriate default
• 6.4 Record decision time for every action in action history
• 6.5 Integrate timer into betting round flow with human timer mode support

7. Observation Tracking Engine

• 7.1 Implement VPIP tracking (count voluntary pot entries / total hands)
• 7.2 Implement PFR tracking (count pre-flop raises / total hands)
• 7.3 Implement Fold-to-CBet tracking (count folds to continuation bets / total CBet faces)
• 7.4 Implement WTSD tracking (count showdowns / total post-flop participations)
• 7.5 Implement per-street bet sizing tracker with pattern detection (small/standard/polarized)
• 7.6 Implement timing tell tracker (fast vs slow distributions per action type)
• 7.7 Wire observation updates to trigger after each completed hand

8. Player Classification Engine

• 8.1 Define weighted scoring functions for all 8 archetypes
• 8.2 Implement confidence calculation based on score magnitude and sample size
• 8.3 Implement minimum sample size check (10 hands before classification)
• 8.4 Implement confidence capping by sample size brackets (10-20: 60%, 20-40: 80%, 40+: uncapped)
• 8.5 Implement secondary pattern detection (bet sizing tendencies, timing tells, bluff frequency)
• 8.6 Integrate classification results into observation data for UI display

9. Table Setup UI

• 9.1 Create visual table layout component showing all seats with poker table aesthetic
• 9.2 Implement seat click handler that opens archetype/skill selection dropdown
• 9.3 Implement quick presets (Fish Table, Regular Grind, High Stakes, Training Mix)
• 9.4 Implement global settings panel (blinds, stack size, player count, timer config)
• 9.5 Implement info level selector (None, Hints, Stats, Full Reveal)
• 9.6 Implement feedback level selector (Off, Post-hand, Real-time)
• 9.7 Wire table setup to initialize GameState with configured bot personalities

10. Info Display System

• 10.1 Create info display component that renders opponent data based on info level
• 10.2 Implement "None" mode (no data shown)
• 10.3 Implement "Hints" mode (occasional contextual pattern hints)
• 10.4 Implement "Stats" mode (raw VPIP, PFR, Fold-to-CBet, WTSD display)
• 10.5 Implement "Full Reveal" mode (all stats + inferred type + confidence + patterns)
• 10.6 Wire dynamic updates to refresh after each hand completion

11. Teaching Coach System

• 11.1 Create post-hand analysis generator that evaluates player decisions vs optimal play
• 11.2 Implement real-time suggestion engine that references opponent observation data
• 11.3 Implement coaching content filtering based on info level (no stat leakage at lower levels)
• 11.4 Implement pattern recognition confirmation detection (3+ consecutive successful exploitations)
• 11.5 Create "Read Confirmed" notification component with lesson reinforcement
• 11.6 Integrate teaching coach into hand completion flow and decision UI

12. Integration & Testing

• 12.1 End-to-end test: full hand plays with personality-driven bot decisions
• 12.2 End-to-end test: timer expires and triggers correct timeout action per archetype
• 12.3 End-to-end test: observation stats accumulate correctly across multiple hands
• 12.4 End-to-end test: classification produces correct type after sufficient sample size
• 12.5 End-to-end test: info display respects chosen level and hides/reveals appropriately
• 12.6 End-to-end test: teaching coach provides feedback matching chosen intensity level
• 12.7 Run svelte-check and fix any type errors