@wattsonclub/wattson-cli 0.0.0-stage → 0.1.0

package/skill/references/workout-building-blocks.md

@@ -0,0 +1,507 @@
+# Workout building blocks
+
+This doc describes the current **atomic workout grammar** in `packages/domain` and how agents should think about composing workouts from it.
+
+It is intentionally agent-oriented.
+
+Goal:
+- make the workout structure legible without reading raw Zod code
+- expose the atomic building blocks that agents can combine
+- make validation/revision loops more reliable
+- establish a stable conceptual vocabulary for future CLI/MCP/chat interfaces
+
+Canonical source of truth remains the domain schema.
+This doc is a human/agent guide, not a replacement for the schema.
+
+Source of truth:
+- `packages/domain/src/index.ts`
+
+---
+
+## 1. Mental model
+
+A workout is:
+- metadata + rationale + constraints
+- a sequence of **blocks**
+- where blocks are either:
+  - simple timed blocks
+  - repeated interval sets
+  - notes/support markers
+
+The useful abstraction for agents is:
+
+1. choose an **objective**
+2. choose a **macro shape**
+3. fill that shape with typed blocks
+4. choose targets/execution modes/cadence/HR constraints
+5. validate
+6. revise until clean
+
+In other words:
+- agents should compose workouts from typed pieces
+- agents should not treat the workout as an opaque paragraph
+
+---
+
+## 2. Top-level workout fields that matter most
+
+These fields drive authoring behavior most strongly:
+
+- `title`
+- `objective`
+- `athleteContext.ftpWatts`
+- `blocks[]`
+- `constraints`
+- `rationale`
+- optional `computed`
+- optional `validation`
+- optional `scheduledDate` (`YYYY-MM-DD`): the day the rider plans to ride it. Set with `schedule_saved_workout`; it orders the library and never starts a ride.
+
+Important practical point:
+- the **blocks** define the actual workout shape
+- the **constraints** define what is allowed/safe/preferred
+- the **validation/computed** fields define whether the workout is coherent/executable
+
+---
+
+## 3. Atomic building blocks
+
+## 3.1 Simple timed blocks
+
+These are the main single-step building blocks.
+
+Supported simple block types:
+- `warmup`
+- `steady`
+- `recovery`
+- `cooldown`
+- `ramp`
+- `free_ride`
+- `cadence_drill`
+- `rest`
+
+Shape:
+- `id`
+- `type`
+- `durationSec`
+- optional `target`
+- optional `title`
+- optional `instructions[]`
+- optional `cadence`
+- optional `hr`
+
+### When to use them
+
+#### `warmup`
+Use for:
+- gradually preparing the rider
+- low-to-moderate progressive openers
+- cadence ramping without heavy load
+
+#### `steady`
+Use for:
+- endurance
+- tempo
+- threshold holds
+- any stable target period
+
+#### `recovery`
+Use for:
+- low-load valleys between work bouts
+- aerobic reset periods
+
+#### `cooldown`
+Use for:
+- winding the session down
+- reducing target and cadence pressure at the end
+
+#### `ramp`
+Use for:
+- explicit increasing/decreasing load phases
+- progressive openers or build segments
+
+#### `free_ride`
+Use for:
+- rider-controlled sections
+- open movement / transitions
+- less prescriptive sections where target control should be loose
+
+#### `cadence_drill`
+Use for:
+- skill emphasis
+- cadence-specific work where the pedaling cue matters as much as the power target
+
+#### `rest`
+Use for:
+- explicit rests distinct from active recovery
+- true low/no-load gaps
+
+---
+
+## 3.2 Interval set block
+
+Composite block type:
+- `interval_set`
+
+Shape:
+- `id`
+- `type: "interval_set"`
+- `repeat`
+- `steps[]`
+- optional `title`
+- optional `instructions[]`
+- optional `cadence`
+- optional `hr`
+
+This is the main repeating composition primitive.
+
+Think of it as:
+- a small local workout pattern
+- repeated `n` times
+
+That makes it the core tool for:
+- VO2 reps
+- threshold reps
+- over/unders (using step structure)
+- cadence skill repeats
+- repeated recovery/work structures
+
+### Allowed interval-set step types
+Inside an `interval_set`, steps can be:
+- `work`
+- `recovery`
+- `steady`
+- `ramp`
+
+This is important:
+- the outer block says “repeat this structure”
+- the inner steps say what the repeated structure actually is
+
+### Good uses
+
+#### Classic 3x VO2
+- interval_set repeat 3
+  - work 2m @ 115% FTP
+  - recovery 2m @ 50% FTP
+
+#### Threshold ladder
+- interval_set repeat 2
+  - steady 6m @ 100% FTP
+  - recovery 2m @ 55% FTP
+
+#### Cadence focus set
+- interval_set repeat 4
+  - steady 1m @ 75% FTP cadence 105+
+  - recovery 1m @ 50% FTP
+
+---
+
+## 3.3 Climb block
+
+Composite terrain block:
+- `climb`
+
+Shape:
+- `id`
+- `type: "climb"`
+- `course` (a `CourseProfile`: name, source, totals, and `segments[]` of `{ distanceM, gradePct }`)
+- optional `pacingPctFtp` (default `0.85`)
+- optional `title`, `instructions[]`, `cadence`, `hr`
+
+A climb is a simulated ascent: the trainer runs in gradient simulation mode and follows the course's grade
+at the rider's virtual position, which the app computes from live watts, rider and bike mass, and the
+profile. The block ends when the rider reaches the end of the course, not on a timer. Its compiled
+`durationSec` is a physics estimate at `pacingPctFtp × FTP` and drives previews, TSS and zone time only.
+
+Rules:
+- `constraints.allowedExecutionModes` must include `"grade"`.
+- Get `course` from the planner's climb catalog (`lookup_climb`), a Strava segment import
+  (`import_strava_segment`), one of the rider's own Strava rides (`import_strava_activity_course`, source
+  kind `strava_activity`, optionally cut to a segment effort or distance window), a Strava route
+  (`import_strava_route`, source kind `strava_route`), a GPX file or public GPX link (`import_gpx_course`,
+  source kind `gpx`), a myCols or climbfinder page (`import_climb_page`, source kind `climb_page`), the
+  road between two places (`build_road_course`, source kind `road`, OpenStreetMap
+  geometry plus raster elevation) or generated terrain
+  (`generate_terrain_course`, source kind `synthetic`: a distance, average grade and shape, deterministic
+  for the same inputs). Saved workouts keep a snapshot of the course, so disconnecting Strava does not
+  remove the climb.
+- `athleteContext.weightKg` improves the estimate (75 kg when absent). Bike mass is fixed internally at 7.5 kg; legacy profile/workout bike weights are ignored. W/kg uses rider weight only.
+- Trainers without simulation mode ride the climb in ERG at the pacing watts.
+
+Validation warns when a course is under 300 m, averages under 1 %, or has grades outside −20..25 % (they
+are clamped for the trainer).
+
+Every ride also gets a virtual distance (`actualMetrics.distanceM`, `ascentM`): climbs from the course
+odometer, ERG steps as a flat road at the recorded power, written into the FIT file so Strava counts the
+mileage. After the ride, `summarize_session` reports each climb the rider started (`summary.climbs`): distance and
+ascent actually ridden from the app's virtual odometer, time, average power, VAM and whether the summit was
+reached. The app's ride history shows the same figures with the profile.
+
+## 3.4 Note block
+
+Support-only block type:
+- `note`
+
+Shape:
+- `id`
+- `type: "note"`
+- `text`
+
+Use for:
+- non-executable guidance
+- rider coaching context
+- explicit reminders that should survive revision/rendering
+
+Agents should use `note` sparingly.
+If the content changes the actual executable session shape, it should probably be a real workout block, not just a note.
+
+---
+
+## 4. Target grammar
+
+Targets are also typed.
+This matters because agents should choose targets intentionally rather than describing them vaguely.
+
+Supported target modes:
+- `open`
+- `watts`
+- `pct_ftp`
+- `zone`
+- `ramp_watts`
+- `ramp_pct_ftp`
+- `resistance_level`
+- `grade_percent`
+
+## 4.1 Practical meaning
+
+### `open`
+No strict load target.
+Good for:
+- free ride
+- easy reset
+- technique-focused movement
+
+### `watts`
+Absolute target.
+Good when:
+- athlete FTP/context is already resolved
+- exact prescription matters
+
+### `pct_ftp`
+Relative target.
+Good default for authoring because:
+- portable across riders
+- easier for agents to reason about conceptually
+
+Important:
+- `%FTP` values are fractional in structured payloads
+- use `0.55` for `55% FTP`
+- use `1.15` for `115% FTP`
+- never pass whole percentages like `55` or `115`
+
+### `zone`
+Zone-based target.
+Good for:
+- simple endurance/recovery prescriptions
+- more human-facing authoring when exact percentage is unnecessary
+
+### `ramp_watts` / `ramp_pct_ftp`
+Progressive target from start -> end.
+Good for:
+- warmups
+- build phases
+- progressive efforts
+
+### `resistance_level`
+Trainer resistance mode target.
+Use when explicitly designing for resistance execution.
+
+### `grade_percent`
+Grade-mode target.
+Use when explicitly designing for grade/simulation execution.
+
+---
+
+## 5. Additional per-block constraints/cues
+
+Blocks and interval steps can also carry:
+
+### cadence
+Shape:
+- `min`
+- `max`
+- `cue`
+
+Use for:
+- skill emphasis
+- spin-up drills
+- low-cadence strength cues
+
+### hr
+Shape:
+- `capBpm`
+- `softCapBpm`
+
+Use for:
+- safety bounds
+- recovery gating
+- keeping endurance/recovery blocks honest
+
+### instructions[]
+Use for:
+- rider-facing execution guidance
+- short coaching prompts
+- reminders that belong to the block itself
+
+Good examples:
+- `Relax shoulders`
+- `Stay seated`
+- `Smooth pedal stroke`
+- `Do not sprint the start`
+
+---
+
+## 6. Workout-level constraints
+
+Workout-level constraints currently include:
+- `maxDurationSec`
+- `maxPctFtp`
+- `maxContinuousWorkSec`
+- `maxHrBpm`
+- `allowedExecutionModes`
+- `disallowStanding`
+- `avoidSprintStarts`
+- `indoorOnly`
+
+These are important because they tell the agent what *not* to build.
+
+Important:
+- `maxPctFtp` is also fractional
+- use `1.2` for `120% FTP`, not `120`
+
+Practical rule:
+- if the user request conflicts with workout constraints, the agent should prefer a legal workout + explanation over inventing an invalid one and hoping validation fixes it later
+
+---
+
+## 7. Composition patterns agents should use
+
+These are not hardcoded templates.
+They are strong composition patterns.
+
+## 7.1 Endurance ride with gentle structure
+- warmup
+- steady endurance block
+- optional cadence drill inserts
+- cooldown
+
+## 7.2 VO2 session
+- warmup
+- interval_set(work/recovery x n)
+- cooldown
+
+## 7.3 Threshold / sweet spot session
+- warmup
+- longer steady work block(s)
+- recovery between blocks if needed
+- cooldown
+
+## 7.4 Skills session
+- warmup
+- cadence_drill or free_ride sections with explicit cadence cues
+- light steady aerobic work
+- cooldown
+
+## 7.5 Recovery session
+- warmup or very gentle open start
+- low-load steady / open blocks
+- cadence comfort cues
+- cooldown optional if already very easy
+
+---
+
+## 8. What agents should usually do first
+
+When authoring from natural language, agents should generally choose in this order:
+
+1. infer the workout objective
+2. infer intended duration
+3. choose whether the workout is mostly:
+   - steady/simple blocks
+   - repeated intervals
+   - skills/free ride
+4. choose target style:
+   - `pct_ftp` is usually the safest authoring default
+   - `zone` is okay for simpler low-intensity prescriptions
+   - `watts` is better when exact absolute load matters
+5. add cadence / HR cues only when they actually help
+6. validate before saving
+
+---
+
+## 9. How validation should fit into authoring
+
+Current validation structure already includes:
+- `status: pass | warn | fail`
+- `issues[]`
+- each issue has:
+  - `code`
+  - `message`
+  - `path[]`
+  - `severity: warning | error`
+
+That is already a strong base for agent loops.
+
+The practical loop should be:
+1. draft from blocks
+2. validate
+3. inspect issue `severity`
+4. use issue `path` to identify which block or step is the problem
+5. revise only the relevant part
+6. validate again
+
+That is much better than “draft once and hope.”
+
+---
+
+## 10. What usually validates/revises well
+
+Agents will usually do better when they:
+- use a clear warmup / work / cooldown shape
+- use `pct_ftp` rather than over-specific absolute watts too early
+- keep repeated sets explicit with `interval_set`
+- keep rider coaching in `instructions[]` rather than in long prose
+- use workout constraints honestly
+- treat `validate` as part of authoring, not as a final optional extra
+
+---
+
+## 11. Common mistakes agents should avoid
+
+### 1. Treating notes as executable structure
+If it affects the ride shape, make it a block.
+
+### 2. Overusing vague prose instead of typed blocks
+The more vague the workout description, the harder it is to revise and validate.
+
+### 3. Using live adaptation to solve pre-execution authoring problems
+If the workout is not yet running, revise the saved workout.
+Do not force everything through `session adapt`.
+
+### 4. Inventing unsupported runtime changes
+Current live ops are bounded.
+Structural edits like “add another interval right now” are not first-class runtime ops today.
+
+### 5. Ignoring constraints and expecting validate to rescue everything
+Validation is a loop, not a magic trash compactor.
+
+---
+
+## 12. Recommended next implementation follow-on
+
+The next code/doc layers that fit this grammar well are:
+- a canonical text notation for workouts
+- a structured/chat-friendly workout renderer
+- validation feedback that references block/step locations more explicitly in human terms
+
+Those should sit on top of this block grammar, not replace it.