Workout Explainer

Integration points

• UI:
  • Workout detail modal
  • Plan screen tooltips
  • Pre-run guidance screen
• Chat: Served through v0/app/api/chat/route.ts with workout-explainer intent
• Database: Workout details from workouts table

Safety & guardrails

• If workout intensity mismatches user level, propose easier substitution and emit SafetyFlag.
• No medical advice; advise stopping on pain/dizziness.
• If weather is extreme, suggest indoor or modified alternatives.
• Always provide at least one easier substitution option.
• Emphasize form over speed for beginners.

Workout type patterns

Easy Run

Purpose: Build aerobic base, recovery, fat adaptation Execution: Conversational pace, relaxed form, low HR (60-75% max) Cues:

• "Should be able to chat comfortably"
• "Nose breathing if possible"
• "Slow is the goal" Mistakes to avoid:
• Starting too fast
• Trying to keep up with faster runners
• Skipping recovery runs Substitutions:
• Shorten duration by 20-30%
• Walk/run intervals
• Indoor treadmill at controlled pace

Tempo Run

Purpose: Lactate threshold training, race pace simulation Execution: Comfortably hard, controlled breathing, HR 75-85% max Cues:

• "Can speak short sentences"
• "Controlled breathing rhythm"
• "Sustainable effort" Mistakes to avoid:
• Going too hard too early
• Poor pacing (uneven splits)
• Not warming up properly Substitutions:
• Fartlek with tempo segments
• Cruise intervals (5min tempo, 2min easy, repeat)
• Sustained hill repeats

Interval Workout

Purpose: VO2max improvement, speed development, running economy Execution: Hard effort with recovery periods, HR 85-95% max Cues:

• "Focus on smooth acceleration"
• "Full recovery between reps"
• "Maintain form even when tired" Mistakes to avoid:
• Inadequate warm-up
• Too fast on first intervals
• Skipping recovery periods Substitutions:
• Reduce interval count by 30-50%
• Extend recovery periods
• Hill repeats (lower impact)

Long Run

Purpose: Endurance building, mental toughness, fat adaptation Execution: Easy-moderate pace, sustained effort, HR 65-80% max Cues:

• "Start conservatively"
• "Fuel every 45-60 minutes"
• "Stay relaxed and efficient" Mistakes to avoid:
• Starting too fast
• Skipping nutrition/hydration
• Running too hard (should be easy-moderate) Substitutions:
• Break into two shorter runs
• Walk breaks every 10 minutes
• Reduce distance by 20-30%

Rest Day

Purpose: Physical recovery, adaptation, injury prevention Execution: No running, active recovery optional Cues:

• "Rest is training too"
• "Light stretching or yoga okay"
• "Focus on sleep and nutrition" Mistakes to avoid:
• "Making up" missed runs
• Intense cross-training
• Feeling guilty about resting Substitutions:
• Gentle walk (20-30 minutes)
• Swimming or cycling (very easy)
• Yoga or stretching routine

Experience-level adaptations

Beginner

• Simpler language, fewer technical terms
• More encouragement and reassurance
• Focus on completion over performance
• Emphasize safety and form
• Suggest walk breaks as normal, not failure

Intermediate

• Include pace/HR targets
• Technical cues for efficiency
• Connection to goal race pace
• Progressive challenge suggestions

Advanced

• Detailed physiological explanations
• Advanced pacing strategies
• Race-specific adaptations
• Performance optimization tips

Telemetry

• Emit ai_skill_invoked with:
  • workout_type
  • experience
  • safety_flags
  • substitution_provided (boolean)
  • latency_ms

Common edge cases

• Bad weather: Provide indoor alternatives
• Injury recovery: Suggest modified versions
• No equipment: Alternatives without treadmill/track
• Time constraints: Shortened versions that maintain workout intent
• Confidence issues: Extra encouragement, break into smaller chunks

Testing considerations

• Test with each workout type
• Verify beginner vs advanced language differences
• Test substitution appropriateness
• Validate cue clarity and actionability
• Test SafetyFlag emission for mismatch scenarios
• Verify purpose explanation accuracy