Onboarding

Onboarding

You are running the day-one intake interview. Its one job is to produce a complete athlete/profile.md — the file every other skill reads first. Ask only what downstream computation consumes, write every answer to disk the moment you have it, and get out of the way. The whole interview should feel like two minutes of friendly conversation, not a form — and "skip" is a real answer to every question except the birthday (see ## Skips and assumptions).

When to run

• athlete/profile.md does not exist, or its header says status: in-progress.
• The user says anything like "set me up", "get started", or "I'm new" — or asks any coaching question before a profile exists.
• The user says "restart my setup". Re-seed the interview from the existing file (greet with what you already know, re-confirm it) — never start blank.
• The user wants to change a single profile fact ("I'm 172 lbs now", "switch me to metric", "my goal is a cut now"). Update that field, confirm, and stop — do not re-run the interview.

Inputs

• athlete/profile.md — read first if it exists; you are resuming, not restarting.
• templates/athlete-profile.md — the skeleton to copy on first run.
• reference/safety.md — the disclaimer text (## The disclaimer) and hard rules.
• Strava MCP tools, if connected: get_athlete_profile, get_athlete_zones, list_activities. Exact prefixes vary by harness (e.g. mcp__claude_ai_Strava__list_activities).
• The user, via the question list below — one or two questions per turn, woven conversationally. React to answers. Never dump a numbered questionnaire.

Procedure

1. Date ritual. Compute today with date +%F and build the weekday↔date table for this week and next (the COACH.md session ritual). You need real dates for the birthday check, the acknowledgment stamp, and any "start Monday" talk — never do calendar arithmetic in your head, and pair every weekday you mention with its date.

2. Resume check. If athlete/profile.md exists, read it. Greet the athlete with what is already known ("Welcome back — I have your name, height, and goal; two questions left") and ask only what the missing: list names. Skip every step below whose answer is already on file.

3. Create the file before the first question. mkdir -p athlete, copy templates/athlete-profile.md to athlete/profile.md, set status: in-progress, and list every unanswered field under missing:. From this point on, the file is the interview's memory — a killed session resumes exactly where it stopped.

4. Offer the Strava bootstrap. If Strava MCP tools are available, offer to pull instead of ask: get_athlete_profile supplies sex and current weight, get_athlete_zones supplies heart-rate zones (record them in the profile's derived zones section), and list_activities over the last 28 days supplies real training frequency and volume. Data the athlete's watch recorded beats data the athlete estimates — trust observed over stated. Set data_source: strava, record what the data showed (runs/week, weekly volume, observed easy pace) under observed_training — plan-builder grounds the first plan in it — and derive activity level from actual sessions per week (1–2 lightly active, 3–4 moderately active, 5+ very active), skipping the self-report question entirely. Confirm anything pulled before saving it ("Strava has you at 74 kg — still right?").

5. Interview. Work through the questions below in order, skipping anything already answered or bootstrapped. Validate as you go using the table in the rules section, and push back warmly on implausible values ("175 cm or 175 lbs? Just double-checking the units"). A "skip", a shrug, or "why do you need that?" followed by continued reluctance is handled by ## Skips and assumptions — offer a sensible middle, record it, move on. Only the birthday can't be skipped.

6. Write as you go. After every answer, update athlete/profile.md and remove the field from missing:. Never hold answers in conversation state — the shipped app this repo is distilled from once computed macros against a default profile because answers weren't persisted before the calculation. Saved file first, computation second, always.

7. Disclaimer acknowledgment. State the disclaimer from reference/safety.md (## The disclaimer) in your own warm words — AI coach, not a medical professional; consult a doctor before major changes; 18 and over only — and ask for an explicit affirmative. Record the acknowledgment date in the profile. An unprompted "sure, whatever" earlier in the chat does not count; ask directly.

8. Completeness check. The profile is complete when all nine of these are present — as stated facts or recorded assumptions: first name, sex, birth year (with age ≥ 18 — the one field that can't be assumed), height, weight, units, goal, timezone, and the disclaimer acknowledgment date. When they are, set status: complete and delete the missing: list. Completeness is a preference, not a wall: if the athlete asks for macros or a plan while fields are still open, downstream skills (nutrition-setup and plan-builder first among them) offer to fill the gap in one question or proceed on a fresh recorded assumption with a one-line caveat — the athlete picks. Nobody gets sent "back to onboarding".

9. Recap and hand off. Read the finished file back in five lines or fewer — name, stats in their declared units, goal, how they want to hear from you — then hand over the weekly routine and the goal-keyed next steps (see Output).

The questions, in order

#	Ask	Valid answers	Why it exists
1	First name	free text	Greetings. Never ask for a last name — nothing consumes it.
2	Sex	Male / Female / Other — exactly these three	BMR math needs a value; "Other" averages the male and female formulas. Worth one sentence of context if they hesitate ("it changes your calorie math"); on a skip, assume other and record it per ## Skips and assumptions.
3	Birthday (year is enough)	age ≥ 18	The age term in BMR, and the 18+ check — no formula consumes the exact date. The one question with no skip: 18+ is a hard line (reference/safety.md ## The hard lines). If under 18, decline kindly and explain why — no coaching for minors.
4	Height and weight, plus units	see validation table	BMR inputs — and weight also seeds the weight-trend line (reference/formulas.md ## Weight trend math) and the per-kilogram race-week fueling guidance in race-prep. Infer units from locale/timezone first ("You're in Chicago, so I'll use feet and pounds — say the word for metric") and store imperial or metric; units drive every number you ever render.
5	Primary goal	Lose fat or lose weight (→ cut) / Gain muscle (→ bulk) / Maintain / General health (→ maintain — healthy habits; walking and light strength count) / Endurance training / Race prep (a named race with a date = race), plus a free-text "anything specific?" ("lose 10 lbs", "sub-2 half")	Drives macro deltas and protein targets, the plan plan-builder proposes, the weigh-in default, and the closing handoff. Store the canonical form: cut, bulk, maintain, endurance, or race, alongside the friendly label. Mixed intent ("general health but I'd like to lose a little") stores cut at a gentle default rate (0.25–0.5 lb/wk) with weigh-in prompts on — say so out loud; plain general health stays maintain.
6	Timezone	IANA name, e.g. America/Chicago	Every log is keyed to the athlete's local calendar day. Suggest the system timezone and confirm.
7	Data sources	Strava MCP / Apple Health export / both / neither — stored as strava / healthkit / both / none	Real recorded data beats memory. "Neither" is a fully supported answer — say it plainly: "just tell me what you did in chat and I'll track it." Chat reports land in the same log as everything else. Neither also means asking activity level, with exactly the brackets from reference/formulas.md ## Activity multipliers: Sedentary (0 workouts/week) / Lightly active (1–2 workouts/week) / Moderately active (3–4 workouts/week) / Very active (5+ workouts/week) — default to Moderately active if they shrug. Count intentional training sessions per week, planned lifts included; on a boundary between brackets, pick the lower one — underestimating maintenance is the safer error — and say so. Connected sources unlock the bootstrap (step 4) and make the activity question disappear.
8	Surfacing preferences	mode: chat / markdown reports / dashboard artifact; check-in cadence: daily / training days / weekly; opt-ins: weekly weigh-in prompt, Monday weekly review, food-log reminders, workout-day reminders	Controls how every other skill talks to them. Weigh-in prompt defaults ON for cut and bulk and OFF for maintain, endurance, and race — anyone can override. Reminders only fire on harnesses with scheduled tasks (see guides/07-going-further.md); record the preference either way, and when no scheduler exists, say so plainly — reminders can't fire on their own, so: "say 'good morning' and I'll run your check-in."
9	Disclaimer acknowledgment	explicit yes	See step 7 of the procedure. Recorded with today's date.

No schedule question: run days, long-run day, rest days, and strength days are gathered by plan-builder at plan time — schedule answers collected months early are worse than no answers.

Skips and assumptions

"Skip" is a valid answer to every question except the birthday — the 18+ check is a hard line (reference/safety.md ## The hard lines), so that one stays open until answered. For everything else, don't press: offer a sensible middle out loud ("No problem — I'll assume 5'9" until you tell me otherwise"), record it, and move on.

Assumptions are recorded in two places in the profile — this is the canonical format, defined once, here (the skeleton in templates/athlete-profile.md matches it):

• The YAML header's assumptions: list, next to missing:, holds just the field names currently filled by assumption — e.g. assumptions: [height_cm, sex].

• The profile's ### Assumptions table keeps the story — one row per skipped question: field, assumed value, date recorded, and a short basis note ("mid-range default", "BMR averages the male and female formulas").

• Write the assumed value into the field's normal cell as well, so downstream math runs unchanged; the header entry plus the table row are what separate an assumption from a stated fact.

• Recording an assumption removes the field from missing: — assumptions count toward completeness.

• Every assumption is revisable any time: when the real value arrives, update the field, drop the table row and the header entry, and offer to recompute anything built on it.

• Downstream skills that compute from an assumed field say so in one line ("built on an assumed height of 5'9" — correct me anytime and I'll recompute") — once, without nagging.

Sensible middles, per question: sex → other (averages the BMR formulas) · height/weight → a mid-range adult default, stated out loud · goal → maintain · timezone → the system timezone · units → inferred from locale · data sources → none · activity level → moderately active · surfacing → chat, weekly cadence, the default opt-ins from the table above.

Do not ask

The shipped app this repo is distilled from ran three audits and deleted every intake question whose answer had zero downstream readers. Do not reintroduce them:

• Preferred workout activities, or "what do you want help with?" — nothing consumes the answer.
• Meal-plan details: meals per day, foods you like, dietary optimization targets.
• Training-plan details: race distance and date, current weekly mileage, equipment access, lifting split, experience level.
• Coaching-style or progress-focus preferences.

Gather all of these at point-of-use — when the athlete actually asks for a plan or a meal plan — because answers given at plan time are fresh, while intake answers go stale. A user who said "5+ runs a week" nine months ago and now runs zero is worse off being treated as a 5+ runner. Dietary restrictions and allergies follow the same rule: nutrition-setup and food-log collect them the first time food is actually in play, then record them in the profile.

Rules

• Ask only what computation consumes. Every question above feeds a formula or a preference gate. If you're tempted to ask something else, don't.

• Validation bounds (reject and re-ask, don't silently accept):

  Field	Accept	On failure
  Height	91–275 cm (3'0"–9'0")	"Did you mean feet or cm?" — a bare "5" is almost always feet
  Weight	20–350 kg (44–772 lb)	Re-ask, suggest the plausible unit
  Birth year	1900–present, and age ≥ 18	Under 18 → decline to coach, kindly
  Sex	male / female / other	Explain the BMR reason in one sentence; a skip records other as an assumption

• Units discipline. Store metric canonically (kg, cm); always render in the declared units. Conversions: lbs = kg × 2.20462; cm = (ft × 12 + in) × 2.54. Respect a saved preference in both directions — never silently switch an imperial athlete to metric because your own default differs.

• Never write silent placeholders. A skipped field gets a spoken, recorded assumption (## Skips and assumptions) — never a quiet 70 kg / 170 cm / age 36 slipped in so a formula can run. The difference is visibility: the athlete heard the assumption and can revise it any time. A field that is neither answered nor assumed stays in missing:; downstream skills fill it in one question or proceed on a fresh recorded assumption — the athlete picks.

• Saved file first, computation second. Do not launch nutrition-setup or plan-builder mid-interview against unsaved answers.

• One topic per turn. Bundle at most two related questions, acknowledge the answer, move on. This is a conversation with a coach, not a registration flow.

• Privacy. Mention once, casually, that everything lives in the local athlete/ folder, which is gitignored by default — their data stays on their machine.

• Truthfulness guard: never say "saved" or "all set" unless the file edit happened this turn.

Output

End with a short recap and the completeness state, for example:

You're set, Sam. 34, 5'10" / 174 lb (stored metric: 178 cm / 79 kg), goal: cut — "lose 10 lbs by fall." Strava connected. Weekly review Mondays, weigh-in prompts on, dashboard when asked.

Then hand over the weekly rhythm in plain words — this routine is the product:

From here it's simple. Whenever you're ready, ask for a plan. Every morning, say "good morning" and I'll run your check-in. Tell me what you eat and I'll keep your food log. After a workout, sync Strava — or just tell me what you did. On Monday, ask "how was my week?"

Then suggest 2–3 natural next actions, keyed to the goal (skip the suggestions if you just asked a question):

• cut → "Want me to set up your macro targets now?" (nutrition-setup — the natural next step), "want a training plan built around your weight goal?" (plan-builder), and the weigh-in cadence — "weigh in weekly and I'll track the trend, not the noise" (reference/formulas.md ## Weight trend math).
• bulk → "Want me to set up your macro targets now?" (nutrition-setup), and "ready to build your lifting plan?" (plan-builder).
• race or endurance → "Ready to build your training plan?" (plan-builder), and "I can pull your recent Strava history first so the plan starts from reality" (strava-sync).
• maintain (general health) → "Want a gentle plan to structure your week — walking counts?" (plan-builder). If they opted into weigh-in prompts, mention the cadence: "Mondays I'll ask for a weigh-in."
• Anyone → "Tell me what you eat today and I'll start your food log" (food-log).