fitness-weekly-review

name

fitness-weekly-review

description

Generate and persist the WEEKLY REVIEW — the look-BACK over a training week on the Cos board via the `fitness` MCP. A focused sub-skill of fitness-coach: it FETCHES the week's health (summary + trends: sleep, HRV, resting HR, steps, workouts), the workouts actually done, the week's training plan (to compare planned vs done), and the daily form scores across the week, then YOU (the agent) author the review — an overall 0–100 score, a prose summary, and structured training / sleep / recovery / nutrition blocks with 3–5 recommendations and a next-week focus — and PERSIST it via `save_weekly_review` (upserted by ISO week). It lands on the `/fitness/weekly-review` history feed. Always with not-medical-advice framing. Use when the user says "how was my training this week", "weekly review", "review my week", "how did my week go", "recap my training week", or otherwise asks to look back on the week's training.

Fitness — Weekly Review (the look-back operator)

This is the weekly-review sub-skill of fitness-coach — read that skill for the shared philosophy, the canonical health taxonomy, and the enable-gate. Here you do one thing: turn "how was my training this week?" into a persisted weekly_review artifact on the board.

The board is a state machine; YOU are the coach. There is no board-side LLM — the board never generates the review. It computes the deterministic numbers (the form score is a board compute you read, you do not recompute it), validates + versions + stores your JSON, and serves it on the /fitness/weekly-review history feed (latest-by-default, page-back, upserted by ISO week). You FETCH the inputs via the fitness MCP, synthesise the review yourself, and save_weekly_review it. The write is attributed to the agent and no board Anthropic key is involved.

Gate (same as fitness-coach). save_weekly_review is an add-on-gated write — it 404s ("Not found — the fitness add-on may be disabled.") when the Fitness add-on is off; tell the user to enable it at /addons and retry (you don't enable it yourself). All the FETCH reads below are ungated — read freely.

NOT MEDICAL ADVICE. A weekly review is an informational estimate, not medical advice — carry that framing whenever you read recovery, load, or sleep. Defer to a professional for any injury, pain, illness, abnormal symptom, pregnancy, or an under-18 user; a "back off / recover" read on low HRV or poor sleep is a conservative default, not clinical judgement.

---

The ISO week + its bounds

The review is keyed on the ISO week (e.g. 2026-W25) — re-saving the same week upserts in place (no duplicate). Resolve the week from the user's intent ("this week" = the current ISO week; "last week" = the prior one) and compute its bounds: Monday (inclusive) to the next Monday (exclusive, half-open) so every FETCH covers exactly that week. Use those as from / to throughout.

---

PROCEDURE — FETCH → GENERATE → PERSIST

1. FETCH the week's health (the aggregate + the series)

• get_health_summary({ from: <Mon>, to: <next Mon> }) — per-type aggregates for the week: sleep {count, avg_hours, avg_deep_hours, avg_rem_hours}, hrv {avg_ms}, resting_hr {avg_bpm}, steps {total, avg_per_day}, workout {count, total_duration_min, total_calories, activities}.
• get_health_trends({ days: 7 }) — the daily series + deltas (sleep, HRV, resting HR, steps, workouts) so you can read direction (improving / flat / declining), not just the average — e.g. HRV climbing back across the week vs. a flat low.

2. FETCH the workouts actually done

• list_health_data({ type: "workout", from: <Mon>, to: <next Mon> }) — the raw sessions: count, per-session activity / duration_min / distance_km / calories. Aggregate to sessions done, total volume (min), total distance (km), and a per-sport breakdown.

3. FETCH plan-vs-actual (planned vs done)

• list_coaching_artifacts({ kind: "training_plan" }) → find this week's plan (match its week to the ISO week; get_coaching_artifact({ id }) to read the days if needed). Compare the plan's prescribed days/sports against what step 2 shows was actually done → a concise vs_plan read (adherence, what was skipped/added). If there's no plan for the week, say so and review on actuals alone.

4. FETCH the form trend (the deterministic readiness number)

• get_form_score({ date }) across the week's days (or get_daily_summary({ date }) per day) — the board's deterministic readiness score 0–100. Average it → avg_form_score and read its direction → form_trend (rising / flat / falling). The board computes this; you only read + average + interpret it — never recompute it.

5. FETCH nutrition (SOFT — don't block on it)

• list_food_log({ from: <Mon>, to: <next Mon> }) (Nutrition add-on) — days logged, avg calories. This is a soft edge: if Nutrition isn't installed/enabled the log is empty — just leave the nutrition block thin (or omit it); the review is not broken because food data is missing. Point the user at /nutrition-chef if they want it.

6. GENERATE the review (this is YOUR judgement)

Synthesise — don't dump the numbers — into the save_weekly_review payload:

• overall_score (0–100) — your weighted read across training (volume + adherence to plan), sleep (duration + quality trend), recovery (HRV / resting HR / form), and nutrition (if logged). One honest number for the week.
• summary — a short prose paragraph: how the week went, the headline win, the headline drag.
• training — { sessions_done, total_volume_min, total_distance_km, sports_breakdown, vs_plan, highlights } (from steps 2–3).
• sleep — { avg_duration_h, avg_deep_h, avg_rem_h, quality_trend, notes } (from step 1).
• recovery — { avg_hrv, avg_resting_hr, fatigue_level, notes } (from steps 1 + 4 — let the form trend inform fatigue_level).
• nutrition (optional) — { days_logged, avg_calories, notes } (from step 5; omit if no log).
• recommendations[] — 3–5 concrete, profile-aware next steps.
• next_week_focus — the one thing to prioritise next week.
• avg_form_score + form_trend (optional) — from step 4.

Respect the athlete's constraints when you advise: the training focus + availability (goal / days) from get_athlete_profile({}), and the body half from the body MCP — trainingStatus (novice|intermediate|advanced) via get_body_profile, current weight + trend via get_body_status, and the free-text body goal via get_body_objective. If there's no profile, the review is weaker — note it and suggest setting one (the fitness-athlete-profile + body-profile skills / the /fitness + /body pages). Validate your own JSON against this shape before saving — the board rejects a malformed body, it does not repair it. English vocabulary only.

7. PERSIST

save_weekly_review({
  week: "<this ISO week, e.g. 2026-W25>",
  overall_score, summary,
  training:   { sessions_done, total_volume_min, total_distance_km, sports_breakdown, vs_plan, highlights },
  sleep:      { avg_duration_h, avg_deep_h, avg_rem_h, quality_trend, notes },
  recovery:   { avg_hrv, avg_resting_hr, fatigue_level, notes },
  nutrition:  { days_logged, avg_calories, notes },   // optional
  recommendations: [ … 3–5 … ],
  next_week_focus,
  avg_form_score,   // optional
  form_trend        // optional
})

Upserts by week — regenerating the same week replaces the prior review, no duplicate.

8. Tell the user

Report the overall_score, the one-line summary, and the next_week_focus; note it's not medical advice. Tell them it's now on the /fitness/weekly-review history feed (latest-by-default, page-back). Optionally offer to run fitness-training-plan to build next week's plan off this review.

---

Guardrails (recap)

• fitness MCP only, via the tools — never bash/curl for health data.
• The board does NOT generate — YOU do. No board-side LLM, no "click Generate" — you author the review and save_weekly_review it. The deterministic form score is the one number the board computes; you read + average + interpret it, never recompute.
• Gate. A 404 = add-on disabled (enable at /addons, then retry). Reads are ungated.
• Upsert by ISO week — re-saving the same week replaces it.
• Profile-aware + English enums only; respect days available + the training focus (athlete profile) and the body trainingStatus + weight + free-text body goal (the body MCP). No profile → weaker review; note it and point at fitness-athlete-profile + body-profile.
• Nutrition is a SOFT dep — empty food log → thin nutrition block, not a fault.
• NOT MEDICAL ADVICE — informational estimate; defer injuries / pain / illness / abnormal symptoms / pregnancy / under-18 to a physician / physiotherapist / qualified coach.