# Phase 5: Expected Value System - Detailed Planning

## Current Phase 5 Outline (from scoring-system.md)

**Goal**: Implement EV calculation and autodraft integration

- [ ] **5.1** Probability distribution storage
  - [ ] Create data structure for probabilities (8 placements)
  - [ ] Admin UI for manual entry (temporary)
  - [ ] Validation (probabilities sum to 100%)

- [ ] **5.2** EV calculation engine
  - [ ] Implement `calculateExpectedValue` function
  - [ ] League-specific calculation based on scoring rules
  - [ ] Batch calculation for all participants in a season

- [ ] **5.3** Daily update job
  - [ ] Create scheduled job/cron
  - [ ] Fetch/update probability distributions
  - [ ] Recalculate all EVs
  - [ ] Log updates

- [ ] **5.4** Autodraft ranking integration
  - [ ] Update draft queue ranking based on EV
  - [ ] Sort available participants by EV
  - [ ] Autodraft picks highest EV available

- [ ] **5.5** Projected totals display
  - [ ] Calculate projected final points (completed + EV of remaining)
  - [ ] Display on standings table
  - [ ] Show in team breakdown

## Context from Previous Q&A

**Q9:** Where does the probability distribution (P(1st), P(2nd), etc.) come from?
- **Answer**: I'd like to come up with a statistical model. We can likely get some futures to help predict, or we can pull in Elo ratings in some situations and then do some monte carlo simulations.

**Q10:** Does EV update based on real results or external data?
- **Answer**: I'd like to update daily based on real results but also model.

**Requirements**:
- League-specific EV (based on that league's scoring rules)
- Updates daily during season
- Not shown on draft board (used internally for autodraft rankings initially)
- Based on probability distribution of placements for each participant

## Database Schema (Already Defined)

```typescript
participant_expected_values {
  id: uuid PRIMARY KEY
  participantId: uuid -> participants.id
  seasonId: uuid -> seasons.id

  // Probability distribution (stored as percentages)
  probFirst: decimal(5,2)   // e.g., 15.50 = 15.5%
  probSecond: decimal(5,2)
  probThird: decimal(5,2)
  probFourth: decimal(5,2)
  probFifth: decimal(5,2)
  probSixth: decimal(5,2)
  probSeventh: decimal(5,2)
  probEighth: decimal(5,2)

  // Calculated EV
  expectedValue: decimal // Based on league scoring

  calculatedAt: timestamp
  updatedAt: timestamp
}
```

---

## Planning Questions

Please answer these questions inline below each one. Add as much detail as you'd like!

### Section 1: Data Sources & Initial Setup

**Q1:** For the initial probability distributions (before we have historical data), what's the priority order?
- Option A: Start with manual admin entry as MVP, then add external sources later
- Option B: Block Phase 5 until we have at least one external data source integrated
- Option C: Other approach?

**ANSWER:**
Manual entry is fine, I'm not entirely sure what the data shape should be yet for you though. Are we thinking using vegas futures, or potentially ELo ratings?

---

**Q2:** For Elo ratings:
- Should we calculate Elo ourselves based on historical results we enter?
- Or fetch from an external source?
- Do we need Elo for all sports, or just specific ones (e.g., F1, tennis)?

**ANSWER:**
I would prefer fetching from an external source to start, and it's only in certain sports. Some sports we'll only have Vegas futures.

---

**Q3:** For futures odds (betting markets):
- Should we fetch these automatically via API?
- Or allow admins to manually enter them?
- How often do futures odds update (daily, weekly)?
- Any specific API providers you have in mind? (Or should we research options?)

**ANSWER:**
Futures odds can just update weekly, really. I don't have any specific API providers in mind, but if you have an idea or can figure one out, I'd love it. If all we can do is manual, I can make that work.

---

### Section 2: Statistical Model Design

**Q4:** Should different scoring patterns use different probability models?
- Playoffs: Bracket-based simulation (team strength × matchup probabilities)?
- Season standings (F1): Performance model based on qualifying/race history?
- Qualifying points (Golf/Tennis): Tournament-by-tournament predictions?
- Or one unified model that adapts to all patterns?

**ANSWER:**
Yes, different scoring patterns should use different probability models, you've got the right idea.

---

**Q5:** When combining multiple data sources (futures + Elo + recent performance), how should we weight them?
- Equal weighting initially?
- Configurable weights per sport?
- Adaptive weighting based on data quality?
- Other approach?

**ANSWER:**
I don't think we'll be combining them but also it's fine to weigh them equally I guess? But really I'd just expect us to pick one method to use.

---

**Q6:** For Monte Carlo simulations:
- How many simulations per participant? (1000? 10000?)
- What parameters do we simulate? (matchup outcomes, performance variance, etc.)
- Should simulation complexity be configurable (simple MVP vs full model)?

**ANSWER:**
10000 at least, maybe 100000? But we should just simulate the winning odds in the system for everyone and then apply it accordingly, not per participant.

---

### Section 3: Real Results Integration

**Q7:** When real results come in (e.g., team eliminated from playoffs, golfer wins a major), how should probabilities update?
- Automatic recalculation based on predefined rules?
- Or manual "Recalculate EVs" button after entering results?
- Should updates be immediate or batched with daily job?

**ANSWER:**
I think a manual recalculate EVs button after entering results makes sense but automatic also fine.

---

**Q8:** For partial results in qualifying sports:
- Example: Golfer wins 1 of 4 majors → their P(1st overall) should increase
- How much should it increase? Based on QP standings? Statistical model?
- Should we show "current ranking EV" vs "final projected EV"?

**ANSWER:**
We should take the actual scores of the existing majors, and sim the majors that are remaining, and use those two combined to calculate EV.

---

**Q9:** For participants already finished:
- Do we still store their probability distribution (all 0% except their final placement)?
- Or remove them from EV calculations entirely?
- Does a finished participant have EV = actual points?

**ANSWER:**
A finished participant will always have EV = actual points. Any system that doesn't give them actual points based on already awarded points is a flawed system, because past results should be used as part of how EV is calculated.

---

### Section 4: Autodraft & Draft Integration

**Q10:** Should autodraft ALWAYS pick highest EV available?
- Or give users options (highest EV, positional needs, etc.)?
- Should it respect manual draft queues at all, or completely override?

**ANSWER:**
Highest EV available is fine for now. It absolutely should not override manual draft queues, that is always first and foremost, no matter what.

---

**Q11:** During manual drafting, should we show EV to help users?
- Display EV next to each available participant on draft board?
- EV-based "recommended picks" feature?
- Or keep EV hidden (only used for autodraft rankings)?

**ANSWER:**
Let's keep it hidden and only use it for the sorting order. Players with higher EV should be higher on the list, and really we'll start thinking about VORP for sorting instead of EV, but this is the start of it.

---

**Q12:** How should draft queue ordering work with EV?
- Auto-sort queue by EV with manual override?
- Show EV in queue UI to help users order manually?
- "Optimize my queue by EV" button?

**ANSWER:**
Don't sort draft queue at all by any sort of EV. The draft queue is only controlled by the user. It's a private number in the draft room, really.


---

### Section 5: UI/UX & Display

**Q13:** What should users see about probabilities/EV?
- Just the final EV number?
- Full probability distribution (bar chart showing P(1st), P(2nd), etc.)?
- Comparison to other participants ("Top 5% EV" badge)?
- All of the above?

**ANSWER:**
Only the final EV number makes sense. We're using that to show projected total points for a manager based on all of their EVs + scored points.

---

**Q14:** Where should EV be displayed?
- Draft board (during draft)?
- Standings page (projected totals)?
- Team breakdown page?
- Participant detail pages?
- All of the above?

**ANSWER:**
Standings page, team breakdown page, participant details pages. Not draft board.

---

**Q15:** How do we explain EV to casual users?
- Tooltip: "Expected Value is the average points this participant is projected to score"?
- Help page with examples?
- Simple vs Advanced view toggle?
- What wording would resonate with your target users?

**ANSWER:**
Call it projected points, that should be good enough.

---

### Section 6: Performance & Scaling

**Q16:** For the daily update job:
- Update ALL participants in ALL seasons every day?
- Or only participants in active/upcoming seasons?
- Priority tiers (active drafts update hourly, active seasons daily, completed seasons never)?

**ANSWER:**
Only update participants in active/upcoming seasons. There is no point in updating a completed season, we know what the actual points are.

---

**Q17:** League-specific EV calculations:
- If we have 100 participants × 50 leagues, that's 5000 EV calculations
- Should we batch these efficiently?
- Cache EVs and only recalculate when scoring rules change or probabilities update?
- Any performance concerns we should address upfront?

**ANSWER:**
So in my head, we'll calculate the P(1st) through P(8th) and store those percentages. And then we can just reference those numbers when calculating EV based on the points scoring for a league. I don't know if it'll be taxing, what do you think? We could probably cache the results as well I guess?

---

**Q18:** For projected totals on standings page:
- Calculate on-demand when page loads?
- Pre-calculate and store with standings snapshots?
- Cache with TTL (e.g., 1 hour)?

**ANSWER:**
I guess precalculate since we're taking the standings snapshots anyhow? What do you think?

---

### Section 7: Phasing & MVP Scope

**Q19:** Should we MVP Phase 5 with a simpler approach first?
- Option A: Start with manual probability entry only, add statistical model later
- Option B: Start with one sport (e.g., NFL playoffs) and one model, expand later
- Option C: Build full system from the start (all sports, all models)
- Option D: Other approach?

Which approach do you prefer and why?

**ANSWER:**
Start with one sport and one model and expand later. Let's start with the base case of using futures odds, since we can likely reuse that in all of the models. We can get more refined afterwards.

---

**Q20:** For qualifying points sports (golf/tennis) with two-phase scoring:
- Should EV reflect "expected QP" → "expected fantasy points"?
- Or just "expected final fantasy points" (skipping QP detail)?
- Show both "projected QP total" AND "projected fantasy points"?

**ANSWER:**
From the backend, I would imagine EV is going to try to predict QP. On the frontend, we can just show them projected fantasy points.


---

## Additional Questions / Notes

Please add any additional thoughts, requirements, or questions you have below:

**YOUR NOTES:**


---

## Next Steps

Once you've answered these questions:
1. Review your answers
2. Let me know when ready
3. I'll create a detailed Phase 5 implementation plan with:
   - Refined task breakdown
   - Data model specifications
   - API/service layer design
   - UI component specifications
   - Testing strategy
   - Migration path from simple → complex models