Sleep & Recovery Methodology

This document describes the scientific methodology and implementation of Pierre’s sleep analysis and recovery intelligence system.

Overview

Pierre’s sleep and recovery system provides:

• sleep quality scoring: Multi-factor analysis based on NSF/AASM guidelines
• HRV analysis: Heart rate variability trend detection for recovery assessment
• holistic recovery scoring: Combines TSB, sleep quality, and HRV
• rest day recommendations: AI-powered training/rest decisions
• evidence-based: Algorithms based on peer-reviewed sports science research

Target audience: Developers, coaches, athletes, and users seeking deep understanding of Pierre’s recovery intelligence.

Table of Contents

• Tool-to-Algorithm Mapping
• 1. Sleep Quality Analysis
• 2. HRV Trend Analysis
• 3. Holistic Recovery Scoring
• 4. Rest Day Recommendation
• 5. Sleep Schedule Optimization
• 6. Configuration
• 7. Scientific References

Tool-to-Algorithm Mapping

This section provides a comprehensive mapping between MCP tools and their underlying algorithms, implementation files, and test coverage.

Sleep & Recovery Tools (5 tools)

Intelligence Module Dependencies

Algorithm Reference Summary

1. Sleep Quality Analysis

Duration Scoring (NSF Guidelines)

Sleep Stage Quality

Pierre analyzes sleep stages based on AASM recommendations:

Efficiency Scoring

Quality Categories

#![allow(unused)]
fn main() {
pub enum SleepQualityCategory {
    Excellent,  // Score > 85, >8 hours, high efficiency
    Good,       // Score 70-85, 7-8 hours
    Fair,       // Score 50-70, 6-7 hours
    Poor,       // Score < 50, <6 hours or low efficiency
}
}

2. HRV Trend Analysis

HRV Metrics

Pierre uses RMSSD (Root Mean Square of Successive Differences) as the primary HRV metric:

Trend Detection

#![allow(unused)]
fn main() {
pub enum HrvTrend {
    Improving,  // 7-day avg > previous 7-day avg
    Stable,     // Within ±5% of previous period
    Declining,  // 7-day avg < previous 7-day avg
}
}

Recovery Status from HRV

#![allow(unused)]
fn main() {
pub enum HrvRecoveryStatus {
    Recovered,              // HRV elevated, ready for training
    Normal,                 // HRV at baseline
    MildlyFatigued,        // HRV slightly suppressed
    SignificantlySuppressed, // HRV markedly below baseline
}
}

3. Holistic Recovery Scoring

Multi-Factor Aggregation

Pierre combines three recovery indicators:

1. TSB Score (Training Stress Balance)

   • Derived from CTL (Chronic Training Load) and ATL (Acute Training Load)
   • TSB = CTL - ATL
   • Positive TSB = fresh, negative TSB = fatigued

2. Sleep Quality Score

   • Composite of duration, stages, and efficiency
   • Weighted by data completeness

3. HRV Score

   • Based on baseline deviation and trend
   • Optional but highly valuable

Weighting Algorithm

#![allow(unused)]
fn main() {
pub enum RecoveryAggregationAlgorithm {
    WeightedAverage {
        // Full data (TSB + Sleep + HRV)
        tsb_weight_full: f64,    // Default: 0.40
        sleep_weight_full: f64,  // Default: 0.35
        hrv_weight_full: f64,    // Default: 0.25

        // No HRV data (TSB + Sleep only)
        tsb_weight_no_hrv: f64,  // Default: 0.55
        sleep_weight_no_hrv: f64, // Default: 0.45
    },
}
}

Data Completeness

Recovery Categories

4. Rest Day Recommendation

Decision Algorithm

The suggest_rest_day tool uses multi-factor analysis:

IF recovery_score < 40:
    STRONGLY recommend rest (confidence: high)
ELSE IF recovery_score < 60:
    Suggest rest or easy training (confidence: medium)
ELSE IF TSB < -20 AND sleep_score < 70:
    Suggest rest despite moderate recovery (confidence: medium)
ELSE:
    Training OK (confidence based on data completeness)

Confidence Scoring

Output Structure

#![allow(unused)]
fn main() {
pub struct RestDayRecommendation {
    pub rest_recommended: bool,
    pub confidence: f64,           // 0-100
    pub recovery_score: f64,       // 0-100
    pub primary_reasons: Vec<String>,
    pub supporting_factors: Vec<String>,
    pub alternatives: Vec<String>, // e.g., "active recovery", "yoga"
}
}

5. Sleep Schedule Optimization

Duration Recommendations

Base recommendations adjusted by training load:

Bedtime Calculation

bedtime = wake_time - target_hours - wind_down_time

Where:

• wake_time: User’s typical wake time
• target_hours: 8-9 hours (adjusted for fatigue)
• wind_down_time: 30 minutes default

6. Configuration

Sleep Parameters

[sleep_recovery]
# Duration thresholds
athlete_min_hours = 7.0
athlete_optimal_hours = 8.0
athlete_max_hours = 10.0

# Stage targets (percentage)
deep_sleep_min_percent = 15.0
deep_sleep_optimal_percent = 20.0
rem_sleep_min_percent = 20.0
rem_sleep_optimal_percent = 25.0

# Efficiency thresholds
efficiency_excellent = 90.0
efficiency_good = 85.0
efficiency_fair = 75.0

Recovery Scoring Weights

[recovery_scoring]
# Full data weights (must sum to 1.0)
tsb_weight_full = 0.40
sleep_weight_full = 0.35
hrv_weight_full = 0.25

# No HRV weights (must sum to 1.0)
tsb_weight_no_hrv = 0.55
sleep_weight_no_hrv = 0.45

TSB Thresholds

[training_stress_balance]
fresh_tsb = 10.0      # Positive TSB indicates freshness
optimal_tsb = 0.0     # Balance point
fatigued_tsb = -10.0  # Negative indicates fatigue
overtrained_tsb = -30.0  # High risk zone

7. Scientific References

Sleep Science

1. Watson, N.F., et al. (2015). Recommended Amount of Sleep for a Healthy Adult. Sleep, 38(6), 843-844.

2. Hirshkowitz, M., et al. (2015). National Sleep Foundation’s sleep time duration recommendations. Sleep Health, 1(1), 40-43.

3. Simpson, N.S., et al. (2017). Sleep and recovery in team sport athletes. British Journal of Sports Medicine, 51(3), 179-186.

HRV and Recovery

4. Shaffer, F., & Ginsberg, J.P. (2017). An Overview of Heart Rate Variability Metrics and Norms. Frontiers in Public Health, 5, 258.

5. Plews, D.J., et al. (2013). Training adaptation and heart rate variability in elite endurance athletes. International Journal of Sports Physiology and Performance, 8(5), 512-519.

6. Buchheit, M. (2014). Monitoring training status with HR measures: Do all roads lead to Rome? Frontiers in Physiology, 5, 73.

Overtraining and Recovery

7. Meeusen, R., et al. (2013). Prevention, diagnosis, and treatment of the overtraining syndrome. European Journal of Sport Science, 13(1), 1-24.

8. Halson, S.L. (2014). Monitoring training load to understand fatigue in athletes. Sports Medicine, 44(Suppl 2), S139-147.

Athlete Sleep

9. Leeder, J., et al. (2012). Sleep duration and quality in elite athletes. International Journal of Sports Physiology and Performance, 7(4), 340-345.

10. Fullagar, H.H., et al. (2015). Sleep and athletic performance: The effects of sleep loss on exercise performance. Sports Medicine, 45(2), 161-186.