Runspector — AI running coach for Garmin

Deep dive into ONE run: time in each HR zone, interval structure (rep count, rep length, work vs recovery HR), weather, performance condition, plus rule-based notes. Default: the latest run with detail. The interval structure is Garmin's auto-detection — if the athlete states a different structure, the athlete is right.

WRITE a proposed session to the athlete's Garmin account: upload the workout, schedule it on the proposal's day, push it to the watch, then read it back and verify structure and targets. Call ONLY after the athlete has seen the preview and explicitly agreed - a request ("plan me 10 km") is not agreement, "yes, put it on the watch" is. Not available to the app's own card runs; there the athlete clicks. Returns what is now on Garmin, with any warning (not pushed because the watch is offline; a mismatch found on read-back). A proposal can be applied once; an unknown or used id says so and lists the open ones.

Record what the athlete SAYS about themselves today: ill, in pain, sore or stressed - or that it is over. Call it when they tell you, in their own words ("I have a cold", "my calf hurts", "legs are heavy from Sunday", "rough week at work"); never from the data alone - a low HRV is not a cold. It changes today's decision in code: ill or pain rest the day whatever the watch says, and after they end it, as many easy days follow as it lasted; sore or stressed take the hard session away. It holds until they say it is over, or runs out after a few days without a new word; saying it again keeps it open. Returns what was recorded and the app's decision for today now. Local only, nothing goes to Garmin; not available to the app's own card runs.

What the app has learned about THIS athlete from their own data, each with its evidence: how many days they run and on which weekdays, their long-run day, a weekly other sport, how consistent they are, their intensity pattern over 28 days, the VO2max trend and whether a measurement is due, Garmin's load focus, resting-HR baseline and zones - and, where a value moved and held, since when. Call it once per conversation after `get_coaching_reference`, and use it to make the advice theirs. It is context, not today's numbers: those come from the other tools, and the decision stays the app's. Read-only; no Garmin call.

The coach's full rule set: how to read the data, today's decision, the planning rules, zones and intensity distribution, the energy boundary and the sources behind each threshold - the same text the app's own coach works from. Call it ONCE per conversation, before the first training advice, and follow it. No arguments, no Garmin call; it reads nothing of the athlete.

Every recorded recovery value for ONE day (default: latest day with data). Use when a single night/day is in question, not for trends.

Time in heart-rate zones across all runs (easy Z1-2 / moderate Z3 / hard Z4-5 / Z5) with percentages — the basis for the 80/20 polarisation question. States how many runs have zone detail, so an incomplete picture is visible.

Workout digest: totals per sport plus the latest workouts, each run classified Quality / Long Run / Easy (from training effect and duration). Use to see what was actually trained before recommending the next session.

Averages of sleep, HRV, resting HR, stress, Body Battery and steps over the last N days plus a snapshot of the latest day. Use for "how has my recovery been?". Aggregates only — never a day-by-day list.

Training-load picture: ACWR with its SOURCE (Garmin's EWMA ratio, or a self-computed fallback that is less reliable), Garmin training status, VO2max with change, and weekly load buckets. VO2max change is only reported when the value actually varied (Garmin carries the last value forward).

Today's readiness verdict GO / EASY / REST with the signals behind it (HRV status, sleep score, Body Battery, resting HR vs 27-day baseline, ACWR, days since the last hard workout). Rule-based and conservative. START HERE for "should I train today?". Carries the app's own decision for today and, on a hard day, WHICH hard session the history calls for (VO2max intervals, threshold reps, or the steady block Garmin measures VO2max from) - explain that, do not pick another; the athlete's goal from their profile when set; the Garmin calendar for the next 14 days, each entry with its weekday, date and schedule id (what propose_change names). Flags stale data explicitly. When the last Garmin sync is older than 30 minutes it syncs first (10-40 s) and says so on top.

Weekly averages of ONE recovery metric over the last N days — for "is my HRV / resting HR / sleep trending up or down?".

VO2max over the last 8 weeks as STEPS (only the days the value really changed — Garmin carries it forward in between) plus a descriptive comparison of the last 28 days with the 28 before (distance, Z5 minutes, easy share, temperature). Use for "why is my VO2max moving?". Descriptive, not causal.

File the athlete's OWN change to their planned week as a proposal: "Friday instead of Saturday", "Tuesday shorter", "no intervals this week", "add an easy run on Thursday". The athlete decides: the change is kept as asked even where the rules disagree - more than the plan's step, two hard days in a row, a hard session in a return week, a run on a rest day or while they said they are in pain. What the rules think of it comes back as `coach:` lines; say them to the athlete in your own words, and suggest a better change in your answer instead of making one they did not ask for. A workout this app did not make can be removed or replaced, not moved. Returns the change with its days and a proposal id. NOTHING is written to Garmin: apply_workout with the id after the athlete's yes; undo_workout takes it back.

Build a polarised training week and file it as ONE proposal: a VO2max session and a threshold session 48 h apart, the long run on its weekday, easy runs between, nothing hard the day before or after the long run, at least one rest day. The sessions go on the days the athlete usually runs, and the quality sessions keep clear of a weekly other sport - read from their history, each an `assumption:` line. Sized from the athlete's own running weeks and read against their history, in code: +10 % by default, held or unloaded on the load ratio, a down week after three weeks up, a return week after a pause, and a measurement week (a steady block in the threshold slot) when VO2max has had no new value for 28 days - each one an `assumption:` line in the preview; explain the line, do not override it. Targets from their own zones, pace from Garmin's race predictions when no threshold is measured. Use when the athlete asks for their week ("plan my week", "what should next week look like"). The calendar wins: a day that already has an entry gets nothing, and a quality session too close to a hard calendar day becomes an easy run - each change is a `calendar:` line. Returns every session with its day and one proposal id; apply_workout with that id puts the package on Garmin after the athlete's yes. Nothing is written here.

Build a structured session for the athlete's route or time budget and file it as a PROPOSAL - warm-up, work reps with targets, recovery jogs, cool-down - sized so the whole thing adds up to the route. Targets come from the athlete's own Garmin zones; anything not measured is listed as an assumption. Use when the athlete asks for a workout ("plan me intervals for my 10 km", "an easy 45 minutes", "a threshold session") or when the readiness verdict calls for a different session than the one on the calendar. Kinds: easy/long (one capped step), threshold (Z4 reps), vo2max (Z5 reps), steady (>= 12 min even effort at threshold - the only shape Garmin measures VO2max from). `day` defaults to today. Returns the preview and a proposal id. NOTHING is written to Garmin: show the preview, and only if the athlete says yes call apply_workout with the id. On an impossible request (route too short) returns why, not a session.

Pull the latest days and workouts from Garmin Connect NOW. Call this first when today's run or last night's sleep is missing. Takes 10-40 s. Read-only towards Garmin; writes only to the local database.

Take a session (or a whole applied week) back OFF the athlete's Garmin calendar. The counterpart of apply_workout: use it when the athlete says the session should not be there after all, or after trying the write path out. It unschedules - the workout stays in their Garmin library, so applying the same proposal again puts it back on a day without building or uploading anything a second time. Only sessions this app uploaded and scheduled are touched; a calendar entry that has changed hands since is left alone and reported. Like apply_workout it needs the athlete's explicit yes, and it is not available to the app's own card runs.