# LIFTFLOW ONBOARDING RECOMMENDATION Status: product and engineering specification only Date: 2026-08-28 Scope: healthy adults using general-purpose resistance training; no medical or rehabilitation prescription ## 1. Executive recommendation LiftFlow v1 onboarding should feel like handing five useful facts to a calm coach, not configuring a training engine. The primary path is **Build one for me**; **Create my own** remains a first-class alternative and bypasses the questionnaire. Collect five required inputs in four short screens: 1. experience and goal; 2. training days and session duration; 3. training environment; 4. optional priorities and known exercise exclusions. Then show one understandable Training Plan preview, explain that it repeats for eight weeks, allow exercise replacement, and require explicit confirmation before activation. Do not ask for sex, anthropometrics, 1RM, a split, rep ranges, volume or block duration. Those answers do not improve a general healthy-adult Starter Plan enough to justify their friction. The first generator should be deterministic, versioned and server-owned. It should create the same `TrainingBlock` / `TrainingPlan` / `PlanExercise` objects as manual creation, with provenance rather than a parallel generated-plan domain. It should make conservative choices and fail before writing anything if the plan is invalid. ## 2. Repository findings ### First-run boundary - `User.onboarding_completed_at` is nullable and the GraphQL viewer exposes `requiresOnboarding`. Migration `identity/0003_auth_acquisition.py` marked pre-existing users as complete; new accounts remain incomplete. - `src/app-shell/root-navigator.tsx` routes every authenticated viewer with `requiresOnboarding=true` to `FirstRunHandoffScreen` before loading domain data. - `src/features/auth/screens/first-run-handoff-screen.tsx` is only a completion message plus logout. There is no onboarding route, completion mutation or Starter Plan handoff. - This is durable across logout, reinstall and devices, but it is currently a hard gate. ### Training Plan domain - Backend ownership is `User -> TrainingBlock -> TrainingPlan -> PlanExercise`. Plans and prescriptions become immutable snapshots after block activation; workout sessions snapshot the prescription again. - A block stores title, free-text goal, start date, target workout count, a one-to-seven-slot cadence, one-to-six plans and a `TrainingBlockState.next_plan` queue cursor. Missed workouts do not consume the queued plan. - `PlanExercise` already stores stable exercise FK, order, sets, rep range, RIR range, rest seconds, optional tempo and a note. Database checks validate only broad storage ranges, not training science, equipment, coverage, duration or weekly volume. - `CreateTrainingBlockCommandHandler` is transactional and idempotent. Activation requires every plan to contain an exercise and enforces one active block per user. - No creation-source or rulebook-version provenance exists. No Starter Plan generator or validator exists. ### Current manual creation - `NewTrainingBlockScreen` asks for a block name, free-text goal, raw `YYYY-MM-DD` start date, cadence sequence, workout-count target and copy-versus-empty plan setup. - A new exercise defaults to 3 sets, 8-12 reps, RIR 1-3 and 120 seconds rest. These are generic UI defaults, not a goal-aware rulebook. - Plans can be added, removed and reordered; exercises can be searched, added, removed, reordered and edited. Plan name, five-character short name and color live on a separate appearance screen. - There is no plan duplication action, day-of-week framing, onboarding entry choice, generated preview, substitution workflow or beginner explanation. - The store retains `prototype` naming, but authenticated mutations are server-first GraphQL calls. It is not merely mock behavior and should not be replaced during onboarding work. ### Exercise catalog and workout feedback - The current local Compose database after all migrations contains **96 active system exercises**. The original seed has 10; historical normalization added the rest. This aggregate count did not inspect production user workout data. - The persisted model and GraphQL API expose only stable UUID, code/name, system/custom ownership and revision. There are no muscles, movement patterns, equipment, difficulty, instructions, substitutions or Starter Plan suitability tags. - The active workout displays the prescribed RIR target, but performed sets store only load and repetitions. Per-exercise feedback is the coarse `easy | good | hard` rating. There is no recorded per-set RIR and no automatic next-load recommendation. - Home can render a `No active block` empty state, but it contains no creation CTA. Sending a new user there via “Do this later” would currently be a dead end. ## 3. Research summary The strongest current synthesis is the 2026 ACSM Position Stand, an overview of 137 systematic reviews and more than 30,000 participants. It finds that many forms of resistance training work, recommends high-effort training of all major muscle groups at least twice weekly, and explicitly prioritizes individualization and participation over rigid prescription. Strength is enhanced by heavier loads, multiple sets, at least two weekly sessions and placing the target lift early. Hypertrophy responds to volume, while load, split/frequency at equal volume, failure training, equipment type and complex periodization are much less decisive for a healthy adult starter program. It proposes 2-3 RIR as a practical near-failure target while acknowledging that exact RIR precision remains uncertain. [ACSM Position Stand (2026)](https://pubmed.ncbi.nlm.nih.gov/41843416/) Additional evidence relevant to v1: - Full-body and split routines produce similar strength and hypertrophy when volume is equated, so LiftFlow can choose the split from schedule and session length rather than asking the user. [Ramos-Campo et al. (2024)](https://pubmed.ncbi.nlm.nih.gov/38595233/) - Training frequency has little independent effect on hypertrophy when weekly volume is equated; frequency is mainly a way to distribute work and fit time. [Schoenfeld et al. (2019)](https://pubmed.ncbi.nlm.nih.gov/30558493/) - Higher loads are more specific to maximal-strength gains, while hypertrophy occurs across a broad load range. [Schoenfeld et al. (2017)](https://pubmed.ncbi.nlm.nih.gov/28834797/) and [Lopez et al. (2021)](https://pubmed.ncbi.nlm.nih.gov/33874848/) - Training to failure is not required. Hypertrophy may trend upward as sets finish closer to failure, but the evidence does not justify exact individualized RIR predictions for a new user. [Robinson et al. (2024)](https://pubmed.ncbi.nlm.nih.gov/38970765/) and [Refalo et al. (2023)](https://pmc.ncbi.nlm.nih.gov/articles/PMC9935748/) - Exercise order primarily improves strength in exercises performed first; hypertrophy does not demand one universal order. Priority and technically demanding work should therefore come early. [Nunes et al. (2020)](https://pubmed.ncbi.nlm.nih.gov/32077380/) - Machines and free weights produce similar hypertrophy; strength gains are specific to the trained modality. Equipment availability and simplicity matter more than a dogmatic modality hierarchy. [Heidel et al. (2023)](https://pubmed.ncbi.nlm.nih.gov/37582807/) - Men and women show similar relative hypertrophy and lower-body strength responses. Observed narrow differences do not justify different general Starter Plan structures, rep ranges, volume or exercise stereotypes. [Roberts et al. (2020)](https://pubmed.ncbi.nlm.nih.gov/32218059/) and [Jones et al. (2025)](https://pubmed.ncbi.nlm.nih.gov/40028215/) - Minimal-dose training can improve strength and function, and time, perceived difficulty and access are participation barriers. A completed conservative plan is commercially and practically better than an “optimal” plan users abandon. [Fyfe et al. (2022)](https://pubmed.ncbi.nlm.nih.gov/34822137/) and [Rhodes et al. (2017)](https://pubmed.ncbi.nlm.nih.gov/28404558/) - Exercise complexity varies meaningfully for novices, supporting a curated novice pool instead of treating the whole catalog as equivalent. [Brenner et al. (2025)](https://pubmed.ncbi.nlm.nih.gov/40041305/) This evidence applies to healthy adults. It does not turn LiftFlow into a medical assessment tool and does not support prescriptions around an injury or disease. ### Competitor patterns - **Fitbod** asks about goal, experience, equipment and duration, but also exposes split and many profile controls. Its useful lesson is that duration changes exercise count and preferences can be learned from replace/skip behavior; LiftFlow can simplify by choosing the split itself. [Fitbod help](https://help.fitbod.me/hc/en-us/articles/360004429814-How-Fitbod-Creates-Your-Workout) - **Hevy** and **Strong** are excellent manual-first trackers: users create routines/templates and then log them. Their public flows illustrate the control path but do not remove the initial programming burden. [Hevy routine builder](https://www.hevyapp.com/use-cases/gym-program-app/) and [Strong templates](https://help.strongapp.io/article/105-about-templates) - **Boostcamp** reduces beginner uncertainty through curated coach programs and explicit progression, but choosing among many named programs and sometimes entering a Training Max still requires knowledge. LiftFlow should produce one conservative default without asking for 1RM. [Boostcamp beginner programs](https://www.boostcamp.app/beginners) - **Alpha Progression** publicly combines a stable generated plan with a manual-from-scratch path, using goal, equipment, frequency and duration. The stable-plan pattern aligns more closely with LiftFlow than regenerating unrelated workouts each day. LiftFlow's differentiator should be a free first plan followed later by evidence-based next-period adaptation. [Alpha Progression](https://alphaprogression.com/) LiftFlow can simplify better by asking no split, no exact equipment inventory, no body metrics and no starting maxes; by producing one stable plan; and by learning availability and preferences from replacements and real workouts. ## 4. Minimum user inputs | Input | Requirement | Why it earns its place | Exact generator effect | | ------------------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Experience | Mandatory | Beginners reliably understand a plain-language self-description, and it affects complexity and conservative starting dose. | Filters exercise complexity; selects 2 versus 2-3 working sets; sets RIR and weekly-volume band. | | Goal | Mandatory | Strength specificity versus hypertrophy volume is supported; the choice also improves motivation. | Selects main-lift rep range/load intent, exercise ordering and lower/upper volume band. | | Training days/week | Mandatory | It determines the number of sessions and how work must be distributed. | Selects the deterministic split, number of plans and seven-day cadence. | | Session duration | Mandatory | Time is a real adherence constraint and materially caps executable work. | Sets exercise, working-set and time budgets; never shortens rest below the safe floor merely to fit more. | | Training environment | Mandatory | It determines which exercises can actually be performed. | Restricts selection to a curated environment-compatible pool. | | Body-part priorities | Optional, maximum two | It can improve autonomy and adherence, but balanced coverage remains more important. | Adds a small amount of weekly volume and earlier order, within global time and volume caps. | | Known exercises to avoid | Optional | A user may know a movement is unavailable or inappropriate without needing a diagnosis flow. | Hard-excludes selected stable exercise IDs before selection and validation. | Do not ask exercise likes in first-run. A beginner may not know; LiftFlow can learn them through Replace, repeated skips and later explicit preferences. ## 5. Inputs rejected ### ASK NOW - Experience, goal, training days, session duration and environment. ### OPTIONAL - Up to two body-part priorities. - Stable exercise-ID exclusions, preferably from the preview/replacement interaction. ### LEARN LATER - Exact days of the week: start from an evenly spaced cadence; let calendar scheduling evolve later. - Exact available equipment: learn an unavailable item through Replace and save it later, rather than presenting a machine checklist. - Exercise preferences, preferred exercise count and actual session pace: infer from replacements, skips, additions and completed workout duration when those signals are reliable. - Preferred rep range and weekly set count: advanced optional settings may exist later, outside the starter questionnaire. ### DO NOT ASK - **Sex/gender:** it does not justify different general exercise selection, split, reps, RIR, progression or volume. Priorities must come from the person, never a stereotype. - **Age:** age does not select a different general plan in the healthy-adult scope. Product/legal age eligibility, if required, is a separate human decision, not a generator input. - **Height, body weight and body-fat percentage:** they do not select the structure of a general plan. Initial load should be learned by performance, not guessed from body size. - **Training age in years:** false precision; the plain-language experience choice is enough. - **Current 1RM:** novices often do not know it, testing it adds risk and friction, and v1 can start conservatively without it. - **Preferred split:** LiftFlow chooses it from days and time. Advanced users can use Create my own. - **Preferred rep range, exercise count and weekly sets:** these are programming decisions promised by Build one for me. - **Exact equipment inventory:** excessive onboarding cost; broad environment plus substitution is sufficient for v1. - **Block duration:** LiftFlow defaults the first period to eight weeks. - **Fat loss:** it does not produce a meaningfully different resistance plan without adding nutrition/cardio scope. The balanced goal remains appropriate; do not promise fat-loss planning. - **Endurance:** outside the first resistance-plan rulebook. “General fitness” would map to the same balanced plan and should not be a fake fourth algorithm. ## 6. Recommended onboarding flow The flow contains an entry screen, four questionnaire screens and a preview. It has five required decisions, not five technical forms. ### Entry — Choose how to start - Primary: **Build one for me** — “Answer a few simple questions. LiftFlow handles the programming.” - Secondary: **Create my own** — “Choose every workout and exercise yourself.” - No paywall and no questionnaire before this choice. ### Screen 1 — Your starting point - Experience: `Starting or returning`, `Some experience`, `Training consistently`. - Goal: `Build muscle`, `Get stronger`, `Muscle + strength`. - Default goal: Muscle + strength. No default experience; it must be intentional. ### Screen 2 — Make it fit your week - Days: 2, 3, 4, 5 or 6; default 3. - Time per session: about 30, 45, 60 or 75 minutes; default 45. - If a starting/returning user chooses 5-6 days, show a nonblocking note that 3 days is usually easier to sustain. Respect the choice and distribute, rather than multiply, weekly volume. ### Screen 3 — Where do you train? - Commercial gym. - Home gym: rack/barbell/bench and weights. - Dumbbells or bands: no rack or machines assumed. - Minimal equipment: body weight and optional simple band. ### Screen 4 — Anything to personalize? (optional) - `No special priority` or at most two of chest, back, shoulders, arms, legs and glutes. - Secondary action: `Exercises I need to avoid`, opening stable-ID search. - Clear Skip action. No free-text injury interpreter. ### Preview — Your Starter Training Plan - Show weekly structure, approximate session time, each workout, exercise prescriptions and a short “Why this plan?” explanation. - Allow Replace on each exercise before confirmation. - Primary: **Use this Training Plan**. Secondary: adjust answers. Tertiary: create manually. - On confirmation, recompute and validate server-side, create the normal plan transactionally, activate it, then mark onboarding complete. ## 7. Create my own path This path bypasses all automatic-plan questions and opens a beginner-friendly manual Training Plan workspace backed by the existing domain. It should start with one workout day and guide the user to: 1. name the Training Plan in user language; 2. add/rename workout days; 3. add and order exercises; 4. optionally edit advanced prescriptions; 5. review and activate. The next implementation should reuse the current builder and change only the first-run handoff and copy necessary to make it reachable. A broader builder redesign should be a separate task. Manual activation must satisfy the same executable-plan invariant, and onboarding can be completed only after an active valid plan exists. ## 8. Build one for me path The client collects the small typed input, but the backend owns normalization, deterministic generation, validation and persistence. The flow must not create a `GeneratedPlan` aggregate. Recommended contract: 1. `starterPlanPreview(input)` deterministically returns a non-persisted, validated draft using stable exercise IDs and `STARTER_RULEBOOK_V1`. 2. The user replaces exercises or edits answers. 3. `createStarterTrainingPlan(clientOperationId, input)` recomputes the same plan, validates it, persists a normal planned block and its plans atomically, activates it using existing invariants, and completes onboarding in the same transaction. 4. A retry with the same operation ID returns the same resource. The client never submits trusted sets/reps/exercise selections as “generated output.” If preview and creation cannot be guaranteed deterministic for the same catalog/rulebook version, the preview must carry a short-lived server draft ID tied to user, normalized input, catalog version and rulebook version. ## 9. Can user defer? **Not in v1.** The current authenticated router is a hard first-run boundary and Home without an active block says only “No active block” with no creation CTA. “Do this later” would move the user from a clear task to a broken empty experience. The user can go back, switch between Build/Create, or log out. Add deferral only after the normal authenticated shell has a coherent no-plan state with prominent Build/Create actions and useful plan-free behavior. ## 10. Beginner education strategy Education is contextual and optional: - Preview: “You'll repeat these workouts for eight weeks so LiftFlow can show what is actually improving.” - Optional **Why?**: “Repeating a stable plan makes changes in reps and weight easier to compare. Later, LiftFlow can use that history to help you decide what should change.” - First RIR display: “Stop when you could still do about 3 clean reps.” Optional **What does this mean?**: “Coaches call this 3 reps in reserve, or 3 RIR.” - First progression prompt: “Reach the top of the rep range with clean form before adding a little weight.” - Do not teach “TrainingBlock” in onboarding. An optional later article may say that a repeated training period is sometimes called a training block. No lecture, forced carousel, anatomy quiz or programming glossary should precede the first workout. ## 11. Current manual Plan Builder UX audit ### What works - It is server-first, idempotent and ownership-protected. - Planned snapshots can be edited without changing earlier blocks; active snapshots are immutable. - Users can search, add, remove and reorder exercises and plans. - Activation is explicit and refuses empty workout plans. - Previous plan copies are independent snapshots. ### Friction and comprehension problems - User-facing copy repeatedly exposes “block”, “cadence”, “queue”, target workout count and snapshot mechanics before a beginner knows why they matter. - The first screen is a long CRUD form. Name, free-text goal, raw date, cadence and workout target are configuration work LiftFlow can default. - Cadence is a numbered training/rest sequence rather than familiar weekly availability. - Creating an empty block is only the start: the user must enter the workspace, manage a plan, possibly edit appearance, search exercises, open each prescription screen and return to activate. - Adding a plan immediately opens name/short-name/color appearance, while the higher-value action is adding exercises. - Prescription labels expose min/max intensity and tempo without progressive explanation. Rest is raw seconds. RPE/RIR depends on a global setting and can be unfamiliar. - Reordering is a separate edit/save mode with up/down actions, and there is no duplicate workout action. - Exercise search cannot filter by muscle, equipment, movement or suitability because the metadata does not exist. - The default 3 x 8-12, RIR 1-3, 120 s prescription is identical for every exercise and goal. ### Recommended later improvements - Present “Training Plan” and “Workout days”; keep `TrainingBlock` internal. - Auto-name, auto-date and auto-calculate the eight-week workout target; place these under optional advanced settings. - Make adding exercises the primary manual action; defer color and short name. - Provide duplicate workout, inline prescription summaries, friendly RIR explanations and a clear review/activate checklist. - Preserve the current backend and server-first workflow. This is UX debt, not a reason to replace the plan architecture. ## 12. Starter Plan Rulebook v1 Rulebook identifier: `STARTER_RULEBOOK_V1`. Every generated plan records this identifier and its creation source. All rules run on the backend. | INPUT | NORMALIZATION | RULE EFFECT | DEFAULT | VALIDATION | | ----------- | ----------------------------------------------- | ----------------------------------------------------- | ---------- | -------------------------------------------------------------------------- | | Experience | `STARTING`, `SOME`, `CONSISTENT` | Complexity pool, sets, volume band, RIR | None | Required enum | | Goal | `MUSCLE`, `STRENGTH`, `BALANCED` | Main rep ranges, main exercise order, volume position | `BALANCED` | Required enum | | Days/week | Integer 2-6 | Split, plan count, seven-day cadence | 3 | Required integer; no duplicates/missing plan positions | | Duration | `30`, `45`, `60`, `75` minutes | Exercise/set/time budgets | 45 | Required enum; generated estimate must fit budget tolerance | | Environment | `GYM`, `HOME_GYM`, `DUMBBELLS_BANDS`, `MINIMAL` | Candidate exercise pool | None | Required enum; every selected exercise compatible | | Priorities | Unique enum list, zero to two | Small volume bonus and earlier order | Empty | Maximum two; cannot remove coverage floor elsewhere | | Exclusions | Unique stable exercise UUID list | Hard candidate exclusion | Empty | IDs must exist and be eligible system exercises; excluded ID cannot appear | Fixed product defaults: - healthy-adult scope; - eight-week period; - target workout count = `days_per_week * 8`; - start date = user's current server-timezone date; - conservative full-range repetitions with controlled technique; - no advanced periodization, supersets, failure sets or tempo prescription in v1; - no starting load guess and no 1RM test. Generation order: 1. normalize and validate input; 2. select split and weekly cadence; 3. build required movement-pattern slots; 4. filter the versioned curated pool by environment, experience and exclusions; 5. deterministically rank candidates using stable rule priority and exercise ID tie-break; 6. assign prescriptions by goal, exercise role and experience; 7. apply priority volume within caps; 8. estimate session duration and remove lowest-priority accessories if over budget; 9. validate the full proposal; 10. return preview or transactionally persist the same normal Training Plan. ## 13. Experience-level rules | Level | Plain-language meaning | Exercise complexity | Starting dose | Effort target | | --------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------- | | Starting or returning | New, inconsistent, or returning after a substantial break | Only low-complexity starter candidates; prefer stable machines/dumbbells over technically demanding barbell variants where the environment permits | Mostly 2 working sets/exercise; 4-6 direct-equivalent weekly sets per major area | About 3 RIR | | Some experience | Knows common movements but has limited consistent programming history | Low and moderate complexity; common barbell movements allowed with simple alternatives | 2-3 sets; 6-10 weekly sets per major area | 2-3 RIR | | Training consistently | Trains regularly and can execute common movements confidently | Low/moderate pool plus selected higher-skill staples; still exclude advanced techniques | Mostly 3 sets; 8-12 weekly sets per major area | About 2 RIR | These are conservative bands, not biological ceilings. Experience must not change user priorities or introduce novelty for its own sake. ## 14. Goal rules ### Build muscle - Prefer moderate rep ranges: 6-10 or 8-12 for compounds, 10-15 for accessories. - Place priority areas early after the first technically demanding compound. - Use the upper half of the experience volume band when time permits. - Do not require failure; target 2-3 RIR. ### Get stronger - Place one goal-relevant, stable compound first in each session. - Consistent trainees may receive 4-6 reps for that main movement; starting/some-experience users use 6-8. Secondary compounds use 6-10 and accessories 8-15. - Use 2-3 sets for main work and longer rest. Do not prescribe singles, max testing or advanced percentage periodization. - Keep whole-body coverage; “strength” must not mean only squat/bench/deadlift. ### Muscle + strength - Default plan. - Main compounds use 6-8 reps, secondary compounds 8-12 and accessories 10-15. - Use the middle of the experience volume band and normal coverage/order rules. ## 15. Frequency/split matrix Frequency distributes weekly work; it does not automatically increase it. | Days | Structure selected by LiftFlow | Seven-slot cadence | Notes | | ---- | --------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------- | | 2 | Full Body A / Full Body B | T R R T R R R | Every major pattern appears across both; ideal minimum. | | 3 | Full Body A / B / C | T R T R T R R | Stable core exercises, not three unrelated workouts. | | 4 | Upper A / Lower A / Upper B / Lower B | T T R T T R R | Allows enough per-session time without asking for a split. | | 5 | Upper A / Lower A / Full Body / Upper B / Lower B | T T T R T T R | Weekly volume is redistributed; full-body day remains concise. | | 6 | Push A / Pull A / Legs A / Push B / Pull B / Legs B | T T T T T T R | Offered for schedule fit, not as a superior default; low per-session volume. | `T` means training and `R` rest. Plans advance by LiftFlow's existing queue, not calendar dates, so a missed day keeps the same next plan. ## 16. Session-duration model | Choice | Working-set budget | Typical exercises | Selection behavior | | ------------ | ------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | | About 30 min | 8-10 | 4 | Required patterns only; compound choices with good coverage; no optional isolation unless a priority replaces another accessory. | | About 45 min | 11-14 | 4-5 | Default; required patterns plus one useful accessory. | | About 60 min | 14-18 | 5-6 | Adds secondary pattern/accessory volume. | | About 75 min | 17-21 | 6-7 | Upper volume band and limited direct priority/arm/core work. | Deterministic estimate per exercise: `transition 75 s + working_sets * (average_set_time + prescribed_rest)` - average set time: 40 s compound, 30 s accessory; - add a five-minute session warm-up allowance; - add one extra two-minute setup allowance for the first loaded compound; - hard acceptance: estimate no more than selected duration + 10%; - if over budget, remove the lowest-priority accessory, then reduce non-priority sets within the volume floor. Never solve time by cutting compound rest below 90 seconds. This is a reproducible heuristic, not a promise that every person finishes at an exact minute. ## 17. Environment/equipment model ### Commercial gym Assume barbells, dumbbells, benches, cable station and common selectorized machines. Prefer low-complexity machines for starting users when they deliver the same pattern simply; do not force barbell lifts. ### Home gym Assume rack, barbell, bench and loadable or adjustable weights. Do not assume cables or specialized machines. ### Dumbbells or bands Assume dumbbells and/or resistance bands, but no rack, barbell or machine. Candidate exercises must have a valid dumbbell/band implementation; a bench cannot be assumed unless the candidate has a floor/standing substitute. ### Minimal equipment Assume body weight and floor space; a simple band may be optional but cannot be required. Plans need scalable progressions/regressions and must not pretend a fixed external-load increment exists. One-tap Replace should show same-pattern alternatives valid for the selected environment. A later saved equipment refinement may be learned from replacements; no machine checklist belongs in v1. ## 18. Priority rules - Priority is optional and limited to two categories: chest, back, shoulders, arms, legs, glutes. - Apply only after minimum balanced coverage is satisfied. - Add at most two direct-equivalent weekly sets per priority for Starting/Some and up to four for Consistent, while remaining within the experience and duration caps. - Move one priority-relevant exercise earlier, but never ahead of a higher-skill main movement when fatigue would make that movement less safe or effective. - Prefer changing an existing exercise selection before adding another exercise. - A priority cannot reduce any major-area floor, remove push/pull balance or turn every session into the same body-part day. - “Glutes” or “chest” comes only from the user's selection, never sex/gender inference. ## 19. Restriction handling - The product asks: “Is there an exercise you already know you need to avoid?” It does not ask for a diagnosis, pain score or medical history. - Exclusions are stable exercise IDs, not free text. They are hard constraints for generation, preview replacement and validation. - If exclusions make a required movement pattern impossible in the chosen environment, generation stops with a safe explanation and offers: change environment, remove an exclusion, or Create my own. It must not silently reintroduce the exercise. - The UI should say that LiftFlow does not diagnose or rehabilitate injury; a user with pain or an uncertain limitation should seek an appropriate qualified professional. - Free-text notes may remain in manual plans but are never interpreted by an AI or rules engine. ## 20. Exercise-selection rules Each weekly plan must cover: - knee-dominant lower body; - hip-dominant/hinge lower body; - upper-body push, including horizontal and vertical across the week; - upper-body pull, including horizontal and vertical across the week; - optional trunk/carry, calf and direct arm work after required coverage. Selection priority, in order: 1. allowed environment and no exclusion; 2. eligible for experience level and `starter_suitable=true`; 3. fills an uncovered required pattern; 4. supports goal/priority; 5. low setup/transition cost for short sessions; 6. consistent reuse across weekly sessions for skill and progression; 7. stable exercise-ID tie-break for reproducibility. Do not select two exercises with the same substitution group in one workout unless the rulebook explicitly needs additional priority volume. Do not select obscure variants merely because they are in the catalog. ## 21. Volume rules Use direct-equivalent sets for deterministic accounting: - primary muscle/pattern contribution = 1.0 per working set; - secondary contribution = 0.5 only where curated metadata explicitly defines it; - no inferred contribution from exercise names. Weekly major-area targets: - Starting/returning: 4-6 sets; - Some experience: 6-10 sets; - Training consistently: 8-12 sets; - muscle goal uses the upper half when duration allows; - strength goal emphasizes 2-3 quality sets on main movements and does not chase volume; - priority bonus remains inside a 12-set v1 cap for a major area. The ACSM finding that hypertrophy is enhanced around 10 or more weekly sets is an optimization signal, not a minimum dose for every novice. LiftFlow deliberately starts conservatively to improve execution and adherence, then can adapt after real history exists. No session may contain more than 10 working sets assigned primarily to one major area. No plan may increase total volume merely because the user selected more training days. ## 22. Sets/reps/RIR/rest rules ### Sets - Default two for Starting, two to three for Some, three for Consistent. - Maximum four only for a Consistent strength user's first main exercise in a 60/75-minute session. - Warm-up sets are not part of the working-set count and are not generated in v1. ### Repetitions - Strength main: 6-8 for Starting/Some; 4-6 for Consistent. - Balanced main: 6-8; secondary compound: 8-12. - Hypertrophy compound: 6-10 or 8-12. - Accessories: 10-15. - Minimal-equipment scalable work: 8-20 where load increments are unavailable. - Avoid 1-3 reps and very high-rep failure work in a general Starter Plan. ### RIR - Starting: 3 RIR. - Some: 2-3 RIR. - Consistent: 2 RIR. - Never prescribe 0 RIR/failure in v1. Present friendly copy before the acronym. ### Rest - Main strength compound: 180 seconds. - Other compound: 120 seconds. - Accessory/isolation: 60-90 seconds. - Short sessions reduce exercises or sets before rest; hard floor 90 seconds for compounds and 60 seconds for accessories. These exact buckets are practical heuristics inside broad evidence-supported ranges, not claims of individual physiological precision. ## 23. Progression rules V1 uses simple double progression without guessing a starting weight: 1. First exposure: the user chooses a controllable load that reaches the lower end of the rep range while leaving the prescribed clean reps in reserve. LiftFlow gives instructions, not a fabricated kilogram recommendation. 2. Next exposure: start from the last successfully recorded load and reps already available through `previousPerformance`. 3. Keep the load and add repetitions within the range. 4. When every prescribed working set reaches the top of the range and exercise effort is `easy` or `good`, suggest the next available small load increase. 5. If effort is `hard`, reps are incomplete or form was not controlled, keep the load; after two consecutive incomplete exposures suggest a small reduction or exercise replacement, without claiming a diagnosis. 6. For bodyweight/minimal equipment, progress reps first, then a curated harder variation only after the top range is achieved. The existing application has no available-increment metadata or next-load recommendation field, and does not record per-set RIR. Therefore the next Starter Plan task should generate prescriptions and guidance only. Automatic numeric load recommendations require a separate, tested implementation using real history and equipment increments; they must not be faked in onboarding. ## 24. Starter Plan validator requirements The minimum server validator must reject before persistence if any condition fails: - input enums, list uniqueness and bounds are valid; - every exercise UUID exists, is active, system-owned, in the versioned curated pool and has complete required metadata; - environment, experience and all excluded IDs are respected; - plan count equals selected days and positions are unique/continuous; - seven-slot cadence contains exactly the selected number of training slots; - every plan has at least one exercise and no exercise appears twice within a plan; - weekly required patterns and major-area volume floors are met; - push/pull and upper/lower coverage is not accidentally omitted; - priority bonuses and global volume caps hold; - sets, reps, RIR and rest meet both database bounds and tighter v1 rules; - exercise ordering satisfies main/priority/accessory rules; - session estimate fits the selected duration tolerance; - target workout count equals days times eight; - no active-block conflict exists at confirmation; - preview/create rulebook and catalog versions match; - the entire create/activate/onboarding-complete operation is atomic and idempotent. Failure returns a user-safe, typed reason and writes no partial block. There is no random fallback and no AI path in v1. ## 25. Exercise taxonomy gaps Current exercise identity is stable enough to reference, but current metadata is insufficient to generate or validate a plan. Minimum versioned metadata per system exercise: - canonical stable ID and display name; - primary and explicit secondary major areas; - movement pattern and push/pull direction; - equipment/environment compatibility; - complexity level; - `starter_suitable` flag; - bilateral/unilateral marker; - compound/accessory role; - substitution-group ID; - default rep-role and rest class; - whether external load is required and whether progression/regression variants exist. Instructions and aliases are important product gaps but are not required to prove the first deterministic plan payload. Exercise names must not be parsed at runtime to infer taxonomy. ## 26. Starter Plan candidate exercise strategy Create a small, reviewed, versioned subset of the 96 system exercises, approximately 24-36 candidates across the four environments. Selection criteria: - common and understandable; - low-to-moderate technical complexity; - broad availability; - measurable progression; - useful coverage with few movements; - clear same-pattern substitutions; - stable identity and non-obscure naming. Do not mark all 96 eligible. The catalog contains specialized cable, angle-specific, neck, BOSU, kettlebell and highly technical variants whose existence does not make them suitable starter defaults. Candidate-pool changes require a new catalog/rulebook version so previews remain reproducible. ## 27. Evidence vs heuristic vs product decisions ### Strong evidence - Resistance training works across many reasonable prescriptions. - Train all major areas at least twice weekly as a general healthy-adult target. - More weekly volume generally produces more hypertrophy with diminishing returns. - Heavier loads are more specific to maximal strength. - Failure is unnecessary; 2-3 RIR is a reasonable general target without exact precision. - Split versus full body and frequency at equated volume are not uniquely outcome-determining. - Sex does not justify separate general Starter Plan rules. ### Reasonable heuristics - The exact 4-6 / 6-10 / 8-12 conservative volume bands by experience. - The specific day-to-split matrix. - Four duration buckets and the deterministic time formula. - Exact rep/rest buckets, priority bonus and candidate-pool size. - Double progression using the current coarse effort signal. ### Product decisions - Five required inputs on four screens. - A free eight-week first period. - 2-6 supported days and default 3. - Four broad environments rather than equipment inventory. - Maximum two optional body-part priorities. - No defer until the no-plan Home experience is useful. - Generated and manual plans share one domain, with provenance. - No AI in Starter Rulebook v1. ## 28. Human decisions required Before implementation, product/training-science approval is required for: 1. whether v1 should offer six days or cap the automatic path at five; this document recommends six for schedule accommodation but never as the default; 2. the final reviewed exercise candidate list and every taxonomy label; 3. exact volume, rep, RIR, rest and priority caps in the heuristic tables; 4. whether the first period is fixed at eight weeks or ends after the equivalent target workout count if adherence extends the calendar; 5. whether a generated plan is activated immediately on confirmation or created as planned and activated by a second explicit action; this document recommends one clear confirmation and an atomic activation; 6. adult eligibility and safety copy, which is a legal/product decision separate from plan personalization; 7. final onboarding visual direction and copy after a clickable prototype is reviewed. ## 29. Recommended exact implementation scope for the NEXT task The next task should implement only the agreed v1 vertical slice: ### Backend - Add versioned exercise taxonomy for a reviewed 24-36-exercise candidate pool. - Add lightweight TrainingBlock creation provenance (`MANUAL | STARTER_RULEBOOK`) and rulebook/catalog version; preserve the shared plan domain. - Implement typed Starter Plan input normalization, pure deterministic generation and validator. - Add preview and idempotent create/activate mutations. Server recomputes; it never trusts a client draft. - Complete `onboarding_completed_at` only in the successful atomic create/activate transaction, or after validating an active executable manually-created plan. - Add exhaustive matrix, invariant, ownership, idempotency, failure/rollback and snapshot tests. ### Frontend - Replace the handoff with entry choice, four short screens and a plan preview. - Add English and Polish copy; other languages fall back to English. - Add answer editing, optional exclusions, exercise Replace, safe errors and retry. - Route Create my own directly to the existing builder with a first-run return path; do not force generator questions. - Preserve auth, remote-data lifecycle and all existing manual/workout behavior. ### Explicitly out of scope - AI, Starter Plan chat, subscriptions, PRO, Plan Review, Adaptive Next Plan, nutrition, injury interpretation, exact equipment inventory, automatic numeric load prediction, broad plan-builder redesign and full exercise encyclopedia. ## 30. Confirmation AGENTS.md was updated with the LiftFlow Product Simplicity Principle Root `AGENTS.md` now contains a dedicated **Product Simplicity Principle** stating that LiftFlow must reduce cognitive load for beginners and recreational lifters; ask only high-information-value questions; avoid or progressively explain jargon; prefer sensible defaults; keep advanced settings optional; make Build one for me remove decisions; keep Create my own as the control path; and require every added UX choice to justify its product value.