Skip to content

v0.3.0 — what comes next

Choose a tag to compare

View all tags
@edxleon edxleon released this 29 Oct 06:24
· 105 commits to main since this release
v0.3.0
bef5b98

The what-comes-next release. You don't need a training plan or a race date: the planner reads your own history to decide what the next week and the next hard session should be. It does this in code, and every rule shows up as a line in the preview.

uv tool install git+https://github.com/edxleon/runcoach-ai@v0.3.0
runcoach serve

The week grows from what you ran

  • The base is the median of your recent running weeks. Weeks are rolling seven-day windows that end on the day you plan, so a Sunday plan counts the week you just ran.
  • The planner adds 10 % to that base, but never goes above 1.1 × the bigger of your last two weeks. Big weeks from months ago no longer set the next one.
  • Brake: a Garmin ACWR above 1.3 holds the week, and above 1.5 cuts it to 75 %. A computed ACWR can only hold.
  • Down week: every fourth week runs at 70 %. That small week is the plan, not detraining.
  • Return week after 10 or more days without a run:
    • easy running only, at 70 % of the weeks before the gap, or 50 % after more than three weeks;
    • your first days back are never a hard day.
  • If a week is too small for all its days, the planner drops days and keeps the sessions the same size. No session is longer than 1.25 × your longest run of the last four weeks.

Which hard session comes next

  • On a hard day the Today tab and get_training_readiness name the stimulus:
    • VO2max intervals if you had no zone-5 stimulus in the last 7 days;
    • a steady measurement block once VO2max intervals are done and a measurement is due;
    • threshold otherwise.
  • A run already on today's calendar is the plan. The app does not suggest a second session next to it.
  • Measurement: if Garmin has given you no new VO2max value from a run for 28 days, one steady block of 12–15 minutes at threshold gives the watch a reading. A value that drifts on a day without a run does not count.
  • Paces: without a measured threshold, the planner uses Garmin's 10k and 5k predictions, if they are recent and consistent, instead of a flat 5:00/km.
  • The rep structure alternates week to week, so you don't run the same 5×4 forever.

Reviewed on purpose

  • Before release, three reviewers and a fresh reader went through these rules. They found 23 cases where the week was wrong exactly when it mattered: after a pause, after weeks that shrank, and right behind a return. All 23 are fixed, each with a test from its scenario that failed on the old code.
  • Live test on a real Garmin account, read-only, after 45 days without a run: an easy day, a return week of 2 × 20 min easy, and a measurement due.

Evals: 27/27

  • Two new cases:
    • a measurement week's steady block is not swapped for intervals because you feel fresh;
    • a down week is explained as progression, with no volume added back.
  • Both fail without the skill files.

Verified

  • 795 Python tests and 66 frontend tests, on Linux, Windows and macOS with Python 3.12 and 3.13, plus the install-as-a-user job.

What's next is in docs/roadmap.md.

Not affiliated with Garmin. A training tool, not medical advice.

Assets 3
Loading