Setup Ralph.

specs/decision-engine.md

@@ -0,0 +1,143 @@
+# Decision Engine Specification
+
+## Job to Be Done
+
+When I check the app, I want a clear training decision based on my current biometrics and cycle phase, so that I avoid overtraining while managing Hashimoto's.
+
+## Decision Status Hierarchy
+
+Decisions are evaluated in priority order. First matching rule wins.
+
+### Priority 1: HRV Unbalanced → REST
+```
+IF hrvStatus == "Unbalanced" THEN REST
+Reason: "HRV Unbalanced"
+```
+
+HRV imbalance indicates autonomic stress. No training.
+
+### Priority 2: Body Battery Depleted → REST
+```
+IF bbYesterdayLow < 30 THEN REST
+Reason: "BB too depleted"
+```
+
+Yesterday's low BB < 30 indicates insufficient recovery.
+
+### Priority 3: Late Luteal Phase → GENTLE
+```
+IF phase == "LATE_LUTEAL" THEN GENTLE
+Reason: "Gentle rebounding only (10-15min)"
+```
+
+PMS window - only gentle movement allowed.
+
+### Priority 4: Menstrual Phase → GENTLE
+```
+IF phase == "MENSTRUAL" THEN GENTLE
+Reason: "Gentle rebounding only (10min)"
+```
+
+Menstruation - even gentler than late luteal.
+
+### Priority 5: Weekly Limit Reached → REST
+```
+IF weekIntensity >= phaseLimit THEN REST
+Reason: "WEEKLY LIMIT REACHED - Rest"
+```
+
+Prevents overtraining within phase constraints.
+
+### Priority 6: Current BB Low → LIGHT
+```
+IF bbCurrent < 75 THEN LIGHT
+Reason: "Light activity only - BB not recovered"
+```
+
+Current energy insufficient for full training.
+
+### Priority 7: Current BB Medium → REDUCED
+```
+IF bbCurrent < 85 THEN REDUCED
+Reason: "Reduce intensity 25%"
+```
+
+Slight energy deficit - reduce but don't skip.
+
+### Priority 8: Default → TRAIN
+```
+ELSE TRAIN
+Reason: "OK to train - follow phase plan"
+```
+
+All systems go - follow normal phase programming.
+
+## Decision Statuses
+
+| Status | Icon | Meaning |
+|--------|------|---------|
+| REST | 🛑 | No training today |
+| GENTLE | 🟡 | Light rebounding only (10-15 min) |
+| LIGHT | 🟡 | Light activity, no intensity |
+| REDUCED | 🟡 | Normal activity, reduce intensity 25% |
+| TRAIN | ✅ | Full training per phase plan |
+
+## Override Integration
+
+Active overrides in `user.activeOverrides[]` bypass algorithmic decision:
+
+| Override | Forced Decision |
+|----------|-----------------|
+| `flare` | REST |
+| `stress` | REST |
+| `sleep` | GENTLE |
+| `pms` | GENTLE |
+
+Override priority: flare > stress > sleep > pms
+
+## Input Data Structure
+
+```typescript
+interface DailyData {
+  hrvStatus: HrvStatus;        // "Balanced" | "Unbalanced" | "Unknown"
+  bbYesterdayLow: number;      // 0-100
+  phase: CyclePhase;           // Current menstrual phase
+  weekIntensity: number;       // Minutes this week
+  phaseLimit: number;          // Max minutes for phase
+  bbCurrent: number;           // 0-100
+}
+```
+
+## Output Decision Structure
+
+```typescript
+interface Decision {
+  status: DecisionStatus;      // REST | GENTLE | LIGHT | REDUCED | TRAIN
+  reason: string;              // Human-readable explanation
+  icon: string;                // Emoji indicator
+}
+```
+
+## Decision Engine (`src/lib/decision-engine.ts`)
+
+**Function:**
+- `getTrainingDecision(data: DailyData): Decision`
+
+## Success Criteria
+
+1. HRV Unbalanced always forces REST regardless of other metrics
+2. Phase limits are respected (no training when limit reached)
+3. Overrides take precedence when active
+4. Decision reason clearly explains the limiting factor
+
+## Acceptance Tests
+
+- [ ] HRV Unbalanced returns REST
+- [ ] BB yesterday low < 30 returns REST
+- [ ] Late luteal phase returns GENTLE
+- [ ] Menstrual phase returns GENTLE
+- [ ] Week intensity >= limit returns REST
+- [ ] BB current < 75 returns LIGHT
+- [ ] BB current 75-84 returns REDUCED
+- [ ] BB current >= 85 with good metrics returns TRAIN
+- [ ] Priority order is maintained (HRV beats BB beats phase)