@wattsonclub/wattson-cli 0.0.0-stage → 0.1.0

package/skill/references/workout-text-format.md

@@ -0,0 +1,460 @@
+# Workout text format
+
+This doc proposes a **chat-friendly, mostly lossless text representation** for workouts.
+
+Goal:
+- make workouts easy to review in chat
+- give agents a stable text representation for reasoning and diffs
+- make structured validation feedback easier to map back to something human-readable
+- prepare for future renderer/parser work without pretending it already exists
+
+Important status note:
+- a first renderer now exists in `packages/domain` via `renderWorkoutText(...)`
+- this is still **not** a fully implemented parser contract yet
+- canonical source of truth is still the structured workout schema in `packages/domain`
+
+Related docs:
+- `workout-building-blocks.md`
+- `commands.md`
+
+---
+
+## 1. Why this exists
+
+Schema is necessary, but schema alone is not enough for chat interfaces.
+
+We need a middle representation that is:
+- readable by humans
+- easy for agents to reason about
+- compact enough for chat
+- stable enough to reference in validation/revision feedback
+- structured enough that it could later become a real render/parse layer
+
+This doc proposes **three textual views** of the same workout:
+
+1. **Expanded canonical text**
+   - most explicit
+   - preferred for careful review
+   - closest to a future reversible representation
+
+2. **Compact text summary**
+   - shorter
+   - good for chat replies
+   - still structurally legible
+
+3. **Chat-visual preview**
+   - highly readable preview
+   - best for quick inspection
+   - not necessarily fully lossless on its own
+
+---
+
+## 2. Design principles
+
+A good workout text format should be:
+
+### Deterministic
+The same structured workout should render the same way every time.
+
+### Block-oriented
+Blocks and interval steps should stay visible as blocks/steps.
+Do not flatten everything into prose.
+
+### Stable enough for references
+Validation should be able to say things like:
+- `block 2`
+- `block 2 > step 1`
+- `line 6`
+
+### Honest about precision
+If a target is explicit, show it explicitly.
+If it is open, show that too.
+
+### Friendly to diffs
+If a workout changes, the text representation should make the change obvious.
+
+---
+
+## 3. Expanded canonical text format
+
+This is the best candidate for a future canonical text representation.
+
+## 3.1 Header fields
+Suggested header fields:
+- `Workout:`
+- `Objective:`
+- `Sport:`
+- `Execution:`
+- optionally `Constraints:`
+- optionally `Rationale:`
+
+Example:
+
+```text
+Workout: VO2 20
+Objective: vo2max
+Sport: cycling_indoor
+Execution: erg
+Constraints: indoorOnly, maxPctFtp=1.2
+Rationale: short hard day with 3 repeat efforts
+```
+
+Note:
+- `maxPctFtp` is fractional
+- use `1.2` for `120% FTP`, not `120`
+
+## 3.2 Block lines
+Each top-level block gets an ordinal prefix.
+
+### Simple block form
+```text
+1. warmup 5:00 @ 55-70% FTP
+```
+
+Or, when more explicit:
+```text
+1. warmup 5:00 target=ramp_pct_ftp(0.55->0.70)
+```
+
+### Interval-set form
+```text
+2. interval_set x3
+  2.1 work 2:00 @ 115% FTP
+  2.2 recovery 2:00 @ 50% FTP
+```
+
+### Note block form
+```text
+3. note "Stay relaxed through the shoulders"
+```
+
+## 3.3 Optional inline annotations
+Add only when present:
+- cadence
+- HR constraints
+- instructions
+
+Example:
+```text
+1. steady 8:00 @ 88% FTP cadence=90-95 note="Stay seated"
+```
+
+Or:
+```text
+1. steady 8:00 @ 88% FTP hr<=165 instructions=["Relax shoulders", "No sprint starts"]
+```
+
+## 3.4 Canonical-ish example
+
+```text
+Workout: VO2 20
+Objective: vo2max
+Sport: cycling_indoor
+Execution: erg
+Constraints: indoorOnly, maxPctFtp=1.2
+
+1. warmup 5:00 target=ramp_pct_ftp(0.55->0.70)
+2. interval_set x3
+  2.1 work 2:00 target=pct_ftp(1.15)
+  2.2 recovery 2:00 target=pct_ftp(0.50)
+3. cooldown 3:00 target=ramp_pct_ftp(0.55->0.45)
+```
+
+This format is not implemented yet, but it is the right target shape.
+
+---
+
+## 4. Compact text summary
+
+This is the shorter chat-friendly view.
+
+Example:
+
+```text
+WU 5m @55->70%
+3x [2m @115% / 2m @50%]
+CD 3m @55->45%
+```
+
+Or, with title/objective:
+
+```text
+VO2 20 — vo2max
+WU 5m @55->70%
+3x [2m @115% / 2m @50%]
+CD 3m @55->45%
+```
+
+This is great for:
+- quick chat confirmation
+- draft previews
+- revision summaries
+
+It is weaker for:
+- exact validation references
+- complex cadence/HR/instruction details
+- future lossless round-tripping
+
+So this should usually be considered a **preview**, not the only representation.
+
+---
+
+## 5. Chat-visual preview
+
+This is the “looks good in a message thread” version.
+
+## 5.1 Linear block preview
+
+```text
+VO2 20
+[WU 5m] [WORK 2m] [REC 2m] [WORK 2m] [REC 2m] [WORK 2m] [REC 2m] [CD 3m]
+ 55-70%    115%      50%      115%      50%      115%      50%     55-45%
+```
+
+## 5.2 Table-like list preview
+
+```text
+VO2 20
+1. Warmup    5:00  55-70%
+2. Work      2:00  115%
+3. Recovery  2:00  50%
+4. Work      2:00  115%
+5. Recovery  2:00  50%
+6. Work      2:00  115%
+7. Recovery  2:00  50%
+8. Cooldown  3:00  55-45%
+```
+
+This is the best format when the user mainly wants to inspect whether the shape “looks right.”
+
+---
+
+## 6. Mapping from structure -> text
+
+## 6.1 Simple block mapping
+
+### Example structured block
+```json
+{
+  "id": "block-1",
+  "type": "steady",
+  "durationSec": 600,
+  "target": { "mode": "pct_ftp", "value": 0.88 },
+  "cadence": { "min": 90, "max": 95 },
+  "instructions": ["Stay seated"]
+}
+```
+
+### Expanded canonical render
+```text
+1. steady 10:00 target=pct_ftp(0.88) cadence=90-95 instructions=["Stay seated"]
+```
+
+### Compact render
+```text
+Steady 10m @88% cadence 90-95
+```
+
+## 6.2 Interval-set mapping
+
+### Example structured block
+```json
+{
+  "id": "block-2",
+  "type": "interval_set",
+  "repeat": 3,
+  "steps": [
+    {
+      "id": "step-1",
+      "type": "work",
+      "durationSec": 120,
+      "target": { "mode": "pct_ftp", "value": 1.15 }
+    },
+    {
+      "id": "step-2",
+      "type": "recovery",
+      "durationSec": 120,
+      "target": { "mode": "pct_ftp", "value": 0.50 }
+    }
+  ]
+}
+```
+
+### Expanded canonical render
+```text
+2. interval_set x3
+  2.1 work 2:00 target=pct_ftp(1.15)
+  2.2 recovery 2:00 target=pct_ftp(0.50)
+```
+
+### Compact render
+```text
+3x [2m @115% / 2m @50%]
+```
+
+---
+
+## 7. Human-friendly target rendering rules
+
+To make chat output readable, we should prefer these human renderings:
+
+- `pct_ftp(0.55)` -> `55% FTP`
+- `ramp_pct_ftp(0.55->0.70)` -> `55-70% FTP`
+- `watts(300)` -> `300W`
+- `ramp_watts(180->260)` -> `180->260W`
+- `zone(z2)` -> `Z2`
+- `open` -> `open`
+- `resistance_level(35)` -> `resistance 35`
+- `grade_percent(4)` -> `grade 4%`
+
+Structured payload rule:
+- `%FTP` values are fractional
+- use `pct_ftp(0.55)` for `55% FTP`
+- use `pct_ftp(1.15)` for `115% FTP`
+- never send `pct_ftp(55)` or `pct_ftp(115)`
+
+This matters because:
+- humans do not want to read raw JSON
+- agents still need a stable rendering convention
+
+---
+
+## 8. Validation feedback and text references
+
+Current validation issues already include:
+- `code`
+- `message`
+- `path[]`
+- `severity`
+
+That is a good foundation.
+
+The text format should help translate issue paths into human-facing references like:
+- `block 2`
+- `block 2 > step 1`
+- `line 6`
+
+### Good future validation examples
+
+```text
+error: block 2 > step 1 exceeds maxPctFtp constraint
+warning: block 1 cadence cue is underspecified for cadence_drill
+error: interval_set x3 causes total duration to exceed requested duration
+warning: cooldown is unusually short for threshold objective
+```
+
+That would make the validate/revise loop much better in chat.
+
+---
+
+## 9. Recommended representation strategy
+
+Use all three, with different purposes:
+
+### Structured schema
+Use for:
+- storage
+- validation
+- revision
+- runtime compilation
+
+### Expanded canonical text
+Use for:
+- careful review
+- agent reasoning
+- diffing
+- future parser/renderer contract
+
+### Compact/chat-visual render
+Use for:
+- chat previews
+- quick approval loops
+- human readability
+
+---
+
+## 10. Practical examples for chat interfaces
+
+## 10.1 User says: "Create me a 20 min session with 3 hard intervals"
+
+Agent could reply with:
+
+```text
+Draft preview — VO2 20
+WU 5m @55->70%
+3x [2m @115% / 2m @50%]
+CD 3m @55->45%
+```
+
+And optionally also keep the canonical-ish version for internal validation/revision.
+
+## 10.2 User says: "Make it slightly easier"
+
+Agent could show a diff-like preview:
+
+```text
+Before:
+3x [2m @115% / 2m @50%]
+
+After:
+3x [2m @110% / 2m @50%]
+```
+
+That makes revision feel concrete.
+
+## 10.3 User says: "Too long — shorten it"
+
+Agent could show:
+
+```text
+Before:
+WU 5m
+3x [2m @115% / 2m @50%]
+CD 3m
+
+After:
+WU 4m
+3x [2m @112% / 90s @50%]
+CD 2m
+```
+
+That is much easier to approve in chat than raw JSON.
+
+---
+
+## 11. Recommended next implementation follow-on
+
+The next practical code step after this doc should probably be:
+
+1. add a renderer helper that turns structured workouts into:
+   - expanded canonical text
+   - compact text summary
+   - chat-visual preview
+2. use that renderer in CLI/docs/tests
+3. later decide whether we want a reverse parser for a canonical text form
+
+Important sequencing point:
+- renderer first
+- parser later, only if it proves valuable
+
+---
+
+## 12. Current implementation status
+
+Currently implemented:
+- `renderWorkoutText(workout, { mode: "compact" | "canonical" | "chat" })` in `packages/domain`
+- compact preview is now used in planner CLI workout summaries where a full structured workout is available
+
+Not implemented yet:
+- reverse parser from text -> workout structure
+- line-stable validation references in CLI output
+- richer diff renderers for workout revisions
+
+## 13. Bottom line
+
+The workout schema should stay canonical.
+But for chat interfaces, agents need a stable text form that sits between:
+- raw JSON
+- vague prose
+
+That is the real leverage point.