DECISIONS.md

DECISIONS.md — Decisions log

A living record of what's decided and what's still open. The agent should treat "Decided" items as fixed and "Open" items as mine to decide — when an open item is needed, ask me rather than choosing. When I make a call, move it from Open to Decided with a one-line note on why.

---

Decided

• Hackathon track: Backyard AI (solving my own real problem).
• Users: single user (me). No multi-profile.
• Goal: hypertrophy + continuous progress; lean bulk (slight surplus or maintenance).
• Architecture: deterministic Python engine (no AI) + small-model parser layer for language only. The parser turns free-text check-ins into structured fields; the engine receives only structured data and never calls AI. (See PROJECT.md.)
• MVP input flow: hybrid first, text-first by MVP completion. The UI starts with a natural-language check-in plus editable structured fields; a small model parser is included in the MVP.
• Build order: UI shell first, then schema, small-model parser, deterministic engine, logging, persistence, deployment, and real-use proof.
• First progression rule: double progression (hit top of rep range on all sets → add load next time). More rules added later from my research.
• MVP load increment: double progression uses a fixed +1 kg load increase when all sets for the latest matching exercise exposure hit the top of the prescribed rep range. Slower, consistent progression is preferred over aggressive jumps that risk early failures and plateaus.
• MVP rep progression: single-rep template prescriptions become a 5-rep progression range with the supplied reps as the middle target. Example: 13 becomes range 11-15 with initial target 13. If the top is not hit, keep load and add up to +2 reps next exposure. If the top is hit on all sets, add +1 kg and reset target reps to the low end of the range.
• Training rule source: hypertrophy_app_training_rules.md is the canonical guide for evidence-based engine behavior. Encode only explicit rules from that document or later user decisions; when the guide gives a range, ask for the concrete MVP default before implementing.
• Hosting/stack: Gradio app on a Hugging Face Space; persistence via a Hugging Face Dataset; GitHub repo with the Space as a second remote.
• Persistence path: use a storage interface; start with local JSON for fast development, then add Hugging Face Dataset storage for durable deployment.
• Persistence badge compromise: local JSON remains the default so the app can run fully locally with no cloud dependency. Hugging Face Dataset storage is optional and enabled only by deployment environment variables; it is durable storage, not cloud AI inference or engine logic.
• Hackathon optimization: prioritize the Backyard AI story: one real user, real logged sessions, a precise small-model language job, deterministic training logic, a live Gradio Space, demo video, and field notes.
• Schema implementation: use Pydantic models in a small training_coach/ package.
• CheckIn schema: raw text, time available, energy level, sleep quality, optional sleep hours, soreness/constraints, pain-or-injury flag, per-issue pain details, mood/stress, and parser notes. pain_or_injury is only a coarse flag; specific painful/problem areas live in pain_issues.
• PainIssue schema: each pain/problem issue represents one affected muscle, severity, and notes. If two muscles are affected, store two PainIssue objects. If the exact muscle is unclear, use affected_muscle = null and ask a follow-up.
• ParsedCheckIn schema: parser output wraps CheckIn with missing fields, structured follow_up_items, display follow_up_questions, context signals, and notes. Context signals capture adjacent correlations such as "ran a 10k yesterday" as a reason to ask about energy or leg soreness. They are not engine decisions.
• Exercise schema: id, name, primary muscle group, secondary muscle groups, compound flag, and rep range. Equipment is intentionally deferred.
• Anatomical muscle enum: use a practical anatomical Muscle enum for exercise tagging, with primary and secondary muscles stored as enum values rather than free text. This supports later pain/constraint filtering.
• Set structure for MVP: use classic straight sets only. Supersets, drop sets, rest pause, and other advanced set types are deferred.
• SessionPlan schema: preserve exercise grouping and execution order. A SessionPlan has date, structured CheckIn, ordered PlannedExercise entries, and notes. Each PlannedExercise has exercise id, order, one or more PrescribedSet entries, and notes. Each PrescribedSet stores set number, target rep range, optional target load, and optional target RIR.
• SessionLog schema: mirror the planned exercise grouping. A SessionLog embeds the planned session and stores ordered LoggedExercise entries. Each LoggedSet stores set number, actual reps, actual load, optional RPE, optional rest seconds before the set, and notes.
• Parser model: local MVP parser uses Ollama qwen3:1.7B by default for speed. Earlier qwen3:4b runs passed the current parser acceptance fixtures after prompt optimization and deterministic parser cleanup. The parser may infer safe structured facts and possible context signals, but it must not invent quantities or training actions. Pain information must use per-issue pain_issues; exercise filtering is performed by the deterministic engine.
• Parser behavior: do not require one-shot perfection. The LLM extracts what it can and proposes structured follow_up_items; deterministic cleanup removes duplicate, already-answered, or unsupported follow-ups before display. Multiple question rounds are acceptable before the engine builds a session.
• Local parser runtime: use Ollama/llama.cpp for local evaluation and development because it is much faster on the Mac than local Transformers CPU/disk-offload. qwen3:1.7B is the current local Ollama default for MVP speed.
• Space parser runtime: Hugging Face Spaces use a GGUF llama.cpp backend, configured with PARSER_BACKEND=llama_cpp, LLAMA_CPP_MODEL_REPO=unsloth/Qwen3-1.7B-GGUF, LLAMA_CPP_MODEL_FILE=Qwen3-1.7B-Q4_K_M.gguf, LLAMA_CPP_MAX_TOKENS=384, LLAMA_CPP_N_CTX=2048, and a Space-specific LLAMA_CPP_N_THREADS. This replaces the slow CPU Transformers runtime. The Transformers backend remains only as an explicit local experiment/fallback path and is not installed by the default requirements.
• MVP training template: use the supplied fixed 4-day exercise template for the first engine slice. Preserve exercise grouping, execution order, set counts, rep targets, and notes. For MVP simplicity, all exercise rests are normalized to 1 minute. No adaptation, progression, or pain filtering is implied by the template itself.
• Today's training day selection: use next-day state from completed session logs. The app should look at the last completed training day, suggest the next day in the 1→2→3→4→1 rotation, and use that history later for double progression. This means logging/persistence is part of the real MVP spine, not a cosmetic add-on.
• MVP history depth: use a minimal completed-session log for the MVP: completed date, training day number, exercise id, set number, actual reps, actual load, and optional RPE/notes. Richer session audit data is a post-MVP improvement.
• Local history file: local development stores completed MVP logs in data/completed_sessions.json, which is ignored by git.
• Performed-set logging UI: do not use a dataframe/table for live workout logging. After building today's session, the app shows one normal input row per prescribed set: prefilled reps, load, optional RPE, and notes. Saving writes only rows with a load into the minimal local history.
• MVP pain filtering: if pain_or_injury is yes and a PainIssue has a known affected muscle, the engine removes exercises whose MVP muscle tags include that muscle, including secondary involvement. It does not substitute replacement exercises yet.
• MVP time compression: use time_available_minutes after pain filtering. At 60+ minutes, run the full remaining plan. At 45-59 minutes, keep roughly 75% of sets. At 30-44 minutes, keep roughly 60% of sets. Under 30 minutes, keep the first four exercises and cap work at 8 sets. Within a compressed plan, preserve exercise order and cut sets from later exercises first.
• MVP readiness adaptation: compute readiness from sleep quality, sleep duration, energy, soreness text, and mood/stress using the guide weights. Apply readiness after pain filtering and time compression. Very low readiness cuts sets about 50% and uses target RIR 4. Low readiness cuts sets about 20% and uses target RIR 3. Normal/high readiness keeps set count unchanged and uses target RIR 2. For MVP, low readiness is score < 3.0 so neutral/okay check-ins do not accidentally reduce the plan.
• Coding agent model: GPT-5.5 in Codex (current recommended default; 5.3-codex is deprecated).

---

Open — mine to decide (agent: ask, don't assume)

1. Training methodology rules

The concrete IF/THEN training rules from my deep research — readiness→session mapping, progression specifics, frequency, exercise ordering, time-compression priorities, (later) periodization and deload triggers and volume targets. Status: researched, not yet encoded. I will hand these over rule by rule. Agent: do not invent these. Ask for the specific rule when the engine needs it.

2. Remaining data schema

No remaining MVP data schema decisions are open right now. Status: CLOSED for the current MVP schema. Reopen only when a new model need appears.

3. Today's training day selection

Use next-day state from completed logs. Status: CLOSED for MVP.

4. Parser acceptance fixtures

The parser model is chosen and parser output is wired into the UI. Fixtures remain as test coverage, not runtime behavior. Status: CLOSED for MVP parser selection.

5. Which stretch features to attempt, and in what order

Defaults in PROJECT.md, but the final call (and when to stop) is mine. Status: OPEN.

---

Notes / parking lot

• Modal (~€250 credits): reserved for a one-time fine-tune or batch job in the stretch phase, not as a live inference backend.
• Proof-of-use for judging = my real logged sessions during the build window + a short demo video showing a short/low-energy day reshaping a session.
• Future schema addition: exercise equipment, once equipment availability/substitution becomes part of the app.
• MVP-relevant guide rules to encode next: review/refine readiness once real logs show whether the score predicts performance.