run-insights-recovery

nadavyigal's avatarfrom nadavyigal

Converts run telemetry into insights, recovery recommendations, and next-session nudges.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026
[Reporting]

When & Why to Use This Skill

The Run Insights & Recovery skill is an AI-driven fitness analytics tool that transforms raw run telemetry into actionable athletic intelligence. By processing metrics such as pace stability, cadence, and heart rate, it provides personalized effort assessments, recovery protocols, and adaptive training suggestions. Designed to bridge the gap between data and performance, it helps users understand their physical output while prioritizing safety through automated health flags and injury prevention guidance.

Use Cases

  • Post-Workout Performance Analysis: Automatically evaluate pace splits and effort levels immediately after a run to provide a comprehensive 'how did I do?' summary.
  • Injury Prevention & Safety Monitoring: Detect safety flags based on missing heart rate data or user-reported pain, providing immediate advice to rest or consult professionals.
  • Adaptive Training Adjustments: Generate 'next-session nudges' that suggest modifying upcoming workouts based on current recovery status and perceived exertion (RPE).
  • Recovery Optimization: Receive specific recovery recommendations and effort mapping (easy/moderate/hard) to ensure training loads remain sustainable.
namerun-insights-recovery
descriptionConverts run telemetry into insights, recovery recommendations, and next-session nudges.
short-descriptionPost-run insights with effort assessment, recovery tips, and safety flags.

When Codex should use it

  • Immediately after a run is saved.
  • When the user asks “how did I do?” or “what should I do next?”

Invocation guidance

  1. Provide RecentRunTelemetry plus derived metrics (pace stability, splits) and upcoming workouts.
  2. Map effort to easy/moderate/hard and generate concise bullets.
  3. Return Insight with RecoveryRecommendation and optional nextSessionNudge.

Input schema (JSON)

{
  "run": RecentRunTelemetry,
  "derivedMetrics": { "paceStability": string, "cadenceNote"?: string, "hrNote"?: string },
  "upcomingWorkouts": Workout[],
  "userFeedback"?: { "rpe"?: number, "soreness"?: string }
}

Output schema (JSON)

Insight

Integration points

  • API/hooks: Post-run pipeline in v0/lib/run-recording.ts and chat surface in v0/lib/enhanced-ai-coach.ts.
  • UI: Today screen banners and run detail modal.
  • Storage: Save alongside run in Dexie via v0/lib/db.ts.

Safety & guardrails

  • If HR missing, default to pace/RPE and add SafetyFlag with missing_data.
  • If user reports pain/dizziness, advise stopping and consulting a professional; downgrade next session.
  • Keep guidance ≤120 words; no medical diagnosis.

Telemetry

  • Emit ai_skill_invoked and ai_insight_created with run_id, effort, safety_flags.