# Spec: Health-Record Ingestion on the Fitness Page (V1)
> **Save to:** `BrainDrive-Library/projects/active/braindrive-fitness/spec.md`
> Generated from `/interview` + draft `/landscape` on 2026-05-20.
> **Status:** V1 draft — review-ready for DJ + DW walkthrough on 2026-05-21. Source decisions: [[decisions.md]] D1–D11. Landscape: [[landscape.md]].
---
## Overview
### What We're Building
**Adding health-record ingestion to the existing Fitness project page in BrainDrive.** Same shape as adding bank-statement ingestion to the Finance page for [[braindrive-budgeting]]: the Fitness page already exists, already runs an interview, already generates a fitness spec + build-plan. This V1 adds an **upload path for blood work + doctor's notes**, **prompts the existing interview to ask for those docs when stated goals warrant it**, and **lets the resulting health context flow into the existing spec + build-plan creation** — so the owner ends up with a fitness spec and build-plan that's actually informed by their real labs and recent visits.
**Not in scope:** building the Fitness page, the fitness interview, the spec template, the build-plan template, the edit-flow mechanics, the sidebar wiring, the goal-handling logic. **All of that exists already.**
**Mental model:** This is the second use case for the [[document-processing]] substrate (budgeting was the first). Substrate is generic; the page-side work is the small wedge of prompt + template guidance + doc-routing-and-detection that lets the page consume health docs intelligently.
### Target User
- **Persona:** Owner — V1 is Dave W only ([[D2]]); V1.1+ broadens.
- **Context:** Owner navigates to the Fitness page (already there), starts (or revisits) the existing fitness interview. When their stated goals warrant it (weight loss, energy, longevity, recovery, anything biomarker-adjacent), the interview now prompts: *"Do you have any recent labs or doctor's notes I should know about?"* Owner uploads → existing substrate parses → existing fitness interview weaves context into the existing spec + build-plan output.
### Problem Statement
BrainDrive's Fitness page produces a fitness spec + build-plan from the existing interview. Today, the only inputs are the owner's stated goals + cross-context from other pages via the owner profile. **The gap is health data** — labs, doctor's notes, prescription lists — that meaningfully shape a fitness plan but currently have nowhere to enter. Without this V1, the owner either omits relevant health context (the plan is worse for it) or uses an external tool (ChatGPT-with-upload) for the health-aware reasoning + then transcribes back to BrainDrive.
Three differentiator pillars (consistent with [[braindrive-budgeting]] D4):
1. **Knows-you advice** — Real health context informs the plan, not just stated goals. Cross-context grounding via owner profile guide ([[D7]]).
2. **Unification** — Owner doesn't need ChatGPT-as-coach for the health-aware planning step; the Fitness page handles it.
3. **Data ownership** — Files stay on owner's BrainDrive instance. No FHIR, no portal aggregator, no model-training exposure ([[D8]]).
---
## User Stories
> All V1 user stories are **Confirmed** by [[decisions.md]] D1–D11 unless noted.
### US-1: Health docs woven into the existing fitness interview — **Confirmed** ([[D5]])
As an owner doing the existing fitness interview, I want BrainDrive to prompt me for relevant health docs when my stated goals warrant it, so the resulting spec + build-plan is informed by my real labs and recent visits.
Details — source, steps, acceptance criteria
**Source:** [[D5]] (V1 use case — health docs are optional context, woven into the existing fitness interview when stated goals warrant it), interview Round 1 + Round 3.
**Steps:**
1. Owner is in the existing fitness interview (creating a fresh spec OR refreshing an existing one — that flow already exists).
2. When the stated goals warrant it (weight loss, energy, longevity, recovery from injury, anything that intersects with biomarkers), the interview asks: *"Do you have any recent labs or doctor's notes I should know about?"*
3. If owner has docs → owner uploads via the existing BrainDrive file-upload UI on the Fitness page. Substrate parses ([[document-processing]] D22 / [[braindrive-models]] D48) → files land under the Fitness page directory (substrate decides the path, see [[Q3]]) → directory's `index.md` is updated ([[braindrive-repo]] D210).
4. Substrate's per-doc `doc_type` classification ([[D12]]) confirms the doc is fitness/health-relevant.
5. The existing fitness interview continues with the parsed content available as context; the AI weaves relevant points into ongoing questions and into the proposed spec + build-plan.
6. **No standalone "health context summary" artifact is created.** Context lives inside the existing spec.md + build-plan.md that the existing flow already produces.
**Acceptance Criteria (Given-When-Then):**
```gherkin
Given the existing fitness interview is running
And the owner's stated goals warrant health context (weight loss / energy / longevity / recovery)
When the interview reaches the relevant moment
Then BrainDrive asks if the owner has recent labs or doctor's notes to share
And does NOT ask for health docs when stated goals don't warrant it (e.g., "I want to run a 10k this fall" with no biomarker-adjacent dimension)
```
```gherkin
Given the owner uploads a lab or doctor's note during the interview
When the substrate finishes parsing
Then the parsed doc lands under the Fitness page directory
And the directory's index.md is updated
And the fitness interview weaves the relevant context into ongoing questions
And the proposed spec + build-plan reflect that context
And NO standalone fitness/health-context.md file is created
```
**Status:** Confirmed
### US-2: Ad-hoc doc upload outside the interview — **Confirmed** ([[D5]], [[D10]])
As an owner who already has a fitness spec, I want to upload a new lab or doctor's note at any time and have the Fitness page recognize it as context — without needing to re-run the whole interview.
Details
**Source:** [[D5]], [[D10]] (re-upload behavior — AI proactively surfaces what changed).
**Steps:**
1. Owner uploads a doc via the existing file-upload UI on the Fitness page, outside the interview.
2. Substrate parses; `doc_type` classification ([[D12]]) confirms it's fitness/health-relevant.
3. If an existing fitness spec + build-plan exist → BrainDrive proactively surfaces *"I see new labs — here's what changed vs. last time; want to update your fitness spec + build-plan?"*
4. If no existing fitness spec → BrainDrive offers to use the upload as context for starting the existing fitness interview (branches into US-1).
**Acceptance Criteria:**
```gherkin
Given a fitness spec + build-plan exist
And the owner uploads a new lab outside the interview
When the substrate finishes parsing
Then BrainDrive surfaces a proactive summary of what changed
And asks whether to update the fitness spec + build-plan
And does NOT update silently
```
**Status:** Confirmed
### US-3: Goal-conflict surfacing when health context conflicts with stated goals — **Confirmed** ([[D5]])
As an owner whose stated goal conflicts with my uploaded health context (e.g., I want to bulk up but my A1c is elevated), I want BrainDrive to surface the conflict in the spec proposal so I can choose how to reconcile — not silently shape the plan around the constraint without telling me.
Details
**Source:** Interview Round 4 — DW: *"AI surfaces the conflict in the spec proposal and asks the owner to choose / refine."*
**Acceptance:**
```gherkin
Given a stated goal that conflicts with available health context
When BrainDrive proposes the spec + build-plan
Then the conflict is surfaced in the proposal
And BrainDrive asks the owner to choose / refine
And does NOT silently compromise or omit the goal
```
**Status:** Confirmed
### US-4: Out-of-scope-doc detection — flag and offer re-route — **Confirmed** ([[D9]])
As an owner who accidentally uploads a non-health doc to the Fitness page (e.g., a bank statement), I want BrainDrive to notice and help me route it to the right page — not silently ingest it as if it were fitness/health context.
Details
**Source:** [[D9]] (out-of-scope-doc detection); mirrors [[braindrive-budgeting]] D24 investment-statement test case.
**Acceptance:**
```gherkin
Given the owner uploads a doc whose doc_type doesn't fit fitness/health
When the substrate finishes parsing and classifies it
Then BrainDrive flags it conversationally ("this looks like a finance doc — want me to route it to Finance?")
And does NOT add it as fitness context
And does NOT silently overwrite the existing spec/build-plan with irrelevant content
```
**Cross-project dependency:** per-doc `doc_type` classification at substrate parse time ([[D12]]) — bundled into DJ's T-619 medical-doc parsing work.
**Status:** Confirmed (depends on substrate `doc_type` field landing)
### US-5: No-docs path — existing fitness interview unchanged when owner has no health docs — **Confirmed** ([[D5]])
As an owner with no health docs to share, I want the existing fitness interview to work the way it does today — not be blocked or made awkward by the new health-doc capability.
Details
**Source:** [[D5]] (docs are optional in V1); regression-protection invariant.
**Acceptance:**
```gherkin
Given the owner has no health docs
When the existing fitness interview runs
Then the prompt for health docs (US-1 step 2) presents naturally and is easy to decline
And declining does not block the interview
And the resulting spec + build-plan is the same shape the existing flow produces today
And no fitness/docs/ folder is created on the owner's BrainDrive
```
**Status:** Confirmed
### US-6: One-time onboarding disclaimer on first health-doc upload — **Confirmed** ([[D6]])
As an owner uploading my first health doc to BrainDrive, I want a clear one-time framing that BrainDrive Fitness is a knowledgeable friend, not my doctor — so I understand the boundary before sharing sensitive data.
Details
**Source:** [[D6]] (disclaimer surface — one-time onboarding + woven into spec/build-plan language).
**Acceptance:**
```gherkin
Given the owner uploads their first health doc to the Fitness page
When the upload completes
Then BrainDrive shows a one-time onboarding disclaimer
And the disclaimer names: knowledgeable-friend framing, clinical-decision boundary, owner-data-stays-local
And the owner acknowledges once
And the disclaimer does NOT re-appear on subsequent uploads
```
**Wording:** Drafted in §Safety & Disclaimer below; DW edits before V1 ship ([[Q1]]).
**Status:** Confirmed (wording TBD)
### US-7: Voice — knowledgeable friend who speculates carefully when discussing health context — **Confirmed** ([[D3]])
As an owner whose health context surfaces in the fitness interview or in the resulting spec + build-plan, I want the AI to speak as a knowledgeable friend who speculates carefully — not as a strict advisor (over-conservative; loses integration value) and not as an AI doctor (over-claims; safety problem).
Details
**Source:** [[D3]] — DW selection in interview Round 1.
**Acceptance — voice rubric (qualitative; tested via test harness AI-judge):**
- **OK:** *"Your A1c at 5.9 is in the pre-diabetic range. For weight loss with that picture, I'd lean cardio-heavy with moderate strength. Worth confirming with your doctor next visit."*
- **OK:** *"This could be why you're feeling tired — your ferritin is on the low end. Mention it next time you see your doctor."*
- **NOT OK (too cocky / diagnostic):** *"You have pre-diabetes. Start metformin and a low-carb diet."*
- **NOT OK (too conservative / unhelpful):** *"Your A1c is 5.9. Please consult your doctor for any interpretation."*
**Status:** Confirmed
---
## Invariants & Edge Cases
### Properties That Must Always Hold
- [ ] **Existing fitness page behavior is preserved.** Adding health-record ingestion must not change how the fitness interview / spec / build-plan / edit flow work for owners with no health docs. Regression protection (US-5).
- [ ] **One upload, one memory file.** Each successful upload produces exactly one parsed memory file under the Fitness page directory (substrate concern; same shape as [[braindrive-budgeting]] D12). No partial writes on parse failure.
- [ ] **No standalone health-context.md.** Health context lives inside the existing spec.md + build-plan.md that the existing flow already produces. There is NO separate `fitness/health-context.md` file as a V1 artifact (interview answer Round 3).
- [ ] **No standalone Health page.** This V1 ships exactly the health-doc ingestion capability on the Fitness page. There is no Health page-product being built ([[D1]]).
- [ ] **Out-of-scope docs do not contaminate the fitness spec.** When the substrate `doc_type` classification flags a doc as non-fitness/health, the doc does not become part of fitness-page context.
- [ ] **Cross-context grounding stays architectural.** Health-doc context flows through the same owner-profile-as-guide mechanism ([[braindrive-repo]] D201 L3) that all cross-page context uses. No direct per-page file reads bypass the owner profile.
- [ ] **PHI never ships in committed test data.** Katie harness fixture is fictional; DW's real labs stay local.
### Edge Cases to Test
- [ ] **Owner with no health docs** (US-5): existing flow unchanged; no folder created; no disclaimer shown.
- [ ] **Owner uploads docs BEFORE starting the interview**: substrate parses; when the existing interview starts later, BrainDrive recognizes the pre-existing context.
- [ ] **Owner declines the in-interview prompt for docs** (US-1 step 2): interview continues without docs; spec acknowledges the absence where relevant.
- [ ] **Parse fails** ([[document-processing]] D22 fallback): error surfaced conversationally; no doc file written; interview can continue without docs.
- [ ] **Out-of-scope doc** (US-4): AI flags + offers re-route. Catches the budgeting-doc-uploaded-to-fitness mistake.
- [ ] **Ambiguous `doc_type` classification** (e.g., a fitness-tracker export that's not a lab or visit summary): AI asks the owner to clarify; doesn't guess silently.
- [ ] **Goal conflicts with uploaded health context** (US-3): AI surfaces + asks owner to refine.
- [ ] **Stale doc** (e.g., 5-year-old lab): AI flags staleness in interview; asks whether to use it as baseline or skip ([[Q4]]).
- [ ] **Re-upload after V1** (US-2): proactive change-summary; owner-driven decision to update spec + build-plan.
- [ ] **Owner asks for symptom triage** ("does this rash mean anything?"): AI declines diagnostic framing per [[D3]]; redirects to "ask your doctor"; does NOT attempt differential.
- [ ] **First health-doc upload triggers the one-time disclaimer** (US-6).
- [ ] **Owner has a goal that obviously belongs on another page** (e.g., "get promoted at work" uploaded as part of fitness goals): existing fitness flow handles this; not a V1 concern for this capability.
### Failure Modes
| Scenario | Expected Behavior |
|----------|-------------------|
| Substrate parse fails on a lab PDF | Error surfaced in chat ([[document-processing]] D22 fallback); no file written; interview can continue. |
| Substrate mis-classifies `doc_type` (e.g., visit summary tagged as imaging report) | Owner uses existing correction flow; consumer reclassifies. |
| Owner uploads a non-fitness/health doc | Out-of-scope-doc detection ([[D9]] / US-4) — flag + offer re-route. |
| Owner runs out of BrainDrive Model credits mid-interview | Existing BrainDrive Model error path handles it; not a fitness-specific concern. |
| Owner uploads PHI in a non-PDF format (e.g., a screenshot) | [[document-processing]] D29 image-upload path handles it. |
| Owner cancels mid-upload | No partial file written; interview state preserved; owner can resume. |
---
## Detailed Requirements
### Core Functionality
- [ ] Health-doc upload path on the Fitness page (reuses existing BrainDrive file-upload UI, same as Finance).
- [ ] Existing fitness interview prompts for health docs when stated goals warrant it ([[D5]], US-1).
- [ ] Parsed health-doc content flows into the existing spec + build-plan creation as context ([[D5]], US-1).
- [ ] Goal-conflict surfacing in the existing spec proposal when health context conflicts ([[D5]], US-3).
- [ ] Out-of-scope-doc detection via substrate `doc_type` classification ([[D9]] / [[D12]], US-4).
- [ ] Re-upload proactive flow ([[D10]], US-2).
- [ ] One-time onboarding disclaimer on first health-doc upload ([[D6]], US-6).
- [ ] Knowledgeable-friend-who-speculates-carefully voice when discussing health context ([[D3]], US-7).
- [ ] Cross-context grounding via owner profile guide ([[D7]]) — architectural, inherited from the existing Fitness page's cross-context behavior.
### User Interface
- [ ] All interaction happens through BrainDrive's existing chat UI + file system + sidebar pattern. **No new UI components.**
- [ ] One-time onboarding disclaimer shown on first health-doc upload ([[D6]]).
- [ ] Fitness page sidebar surface is unchanged (existing fitness/spec.md + fitness/build-plan.md surface stays the way the existing Fitness page wires it).
### Data & State
- [ ] Uploaded health docs are written by the substrate under the Fitness page directory. Exact path: substrate decides per [[document-processing]] D31 + [[braindrive-repo]] D210; see [[Q3]] for path confirmation.
- [ ] Directory `index.md` is BrainDrive-maintained per [[braindrive-repo]] D210.
- [ ] **NO** `fitness/health-context.md` — not a V1 artifact. Health context lives inside the existing fitness/spec.md + fitness/build-plan.md.
- [ ] Substrate-side per-doc `doc_type` classification ([[D12]]) — cross-project ask folded into DJ's T-619 medical-doc parsing work.
---
## Scope
### Feature Type
- [x] **Production** (V1 MVP, owner-facing dogfood). Real owner relies on this; no skipped error handling.
### Implementation Location
- [x] **Page-side prompt + template extension** — fitness page agent.md + spec template + build-plan template ([[braindrive-repo]] D214) get guidance for when to prompt for health docs, how to weave the resulting context into spec/build-plan creation, how to phrase the knowledgeable-friend voice when surfacing health context.
- [x] **Substrate extension (cross-project)** — per-doc `doc_type` classification field in the substrate parsing prompt ([[D12]] / [[Q2]]). Same magnitude as [[braindrive-budgeting]] D22 per-transaction `type`. Owned by DJ in T-619.
- [x] **One-time disclaimer hook** — first-health-doc-upload trigger on the Fitness page.
- [ ] Plugin — not a fit.
**Scope of core changes:**
- Fitness page agent.md / spec template / build-plan template additions ([[braindrive-repo]] D214).
- Substrate `doc_type` field (cross-project, T-619).
- One-time disclaimer hook.
**Explicitly NOT in scope (already exists):**
- The Fitness page itself.
- The existing fitness interview flow.
- The existing spec + build-plan generation.
- The existing edit flow (conversational + direct file edit).
- The existing sidebar wiring.
- Multi-goal handling.
- Goal taxonomy / interview question shape.
- The owner profile / cross-context mechanism (architectural; [[braindrive-repo]] D201).
- Anything Finance-page-specific.
---
## MVP Scope (v1)
### Included (Confirmed via D1–D11)
- US-1 health docs woven into existing fitness interview when goals warrant it.
- US-2 ad-hoc doc upload + proactive change surfacing.
- US-3 goal-conflict surfacing.
- US-4 out-of-scope-doc detection + route.
- US-5 no-docs regression protection.
- US-6 one-time onboarding disclaimer.
- US-7 knowledgeable-friend-who-speculates-carefully voice for health-context moments.
- Substrate per-doc `doc_type` field ([[D12]]).
- Default model = inherited BrainDrive Model ([[D4]] / [[braindrive-models]] D48 Flash 3.5; in flux).
### Explicitly Excluded (v1)
| Item | Why | Where it goes |
|------|-----|---------------|
| Standalone `fitness/health-context.md` artifact | Health context lives inside existing spec + build-plan | Never (architectural) |
| Standalone Health page-product | DW reframe: health is part of fitness | If owners want it, they create it via project-sharing ([[braindrive-repo]] D209) |
| Progress tracking (workout / weight / lab trend logging) | Existing Fitness page V1.1+ scope, not health-doc-V1 | V1.1 of Fitness page |
| Wearable data ingestion | Out of scope per [[D8]] no-aggregator stance | V2 |
| FHIR / MyChart auto-pull | Violates [[D8]] | Never (or owner-instance-side V2+) |
| Symptom triage / differential diagnosis | Safety boundary per [[D3]] | Never |
| Telehealth booking | Different product | Never |
| Family / pediatric tracking | Audience deferred | V2+ |
| Generating a separate "questions to ask your doctor" doc | V1.1+ candidate (pre-visit prep flow) | V1.1+ |
| Restructuring or re-specifying the existing Fitness page | Out of scope; the existing page is the substrate this work sits on | Never (this V1) |
---
## Future Versions
### V1.1 (likely the next push, post-V1 dogfood)
In rough priority order from [[landscape.md]] §6:
1. **Pre-doctor-visit prep flow** — *"I have an appointment Friday"* → BrainDrive surfaces relevant recent uploads + suggests questions.
2. **Lab-trend reasoning across multiple uploads** — when 2+ panels have accumulated, surface trends in the spec + build-plan re-generation.
3. **Apple Health export ingestion** — file-based; respects no-aggregator stance.
4. **Imaging-report deep-read** — V1 substrate parses imaging; V1.1 reasons more deeply.
5. **Tighten the re-upload proactive flow** ([[D10]]) — more sophisticated change-detection across multiple labs.
### V2+ (longer-term)
- Owner-instance-side FHIR pull (consistent with no-third-party-aggregator).
- Wearable data ingestion via vendor-export files (still no live APIs).
- Family-member profiles.
---
## Technical Context
### Integration Points
- [x] **[[document-processing]] substrate** — Hard upstream dependency. Same Haiku/Flash 3.5 path as budgeting. **Cross-project ask:** per-doc `doc_type` classification ([[D12]]) bundled into DJ's T-619 medical-doc parsing work.
- [x] **Existing Fitness page on BrainDrive** — page-side agent.md + spec template + build-plan template per [[braindrive-repo]] D214 get the health-doc-aware additions. **The Fitness page itself is not being built.**
- [x] **BrainDrive Model** — inherited default (Flash 3.5 per [[braindrive-models]] D48; in flux). Same external-brain tool architecture as budgeting ([[braindrive-repo]] D203).
- [x] **Owner profile as cross-context guide** ([[D7]]) — architectural, inherited from existing Fitness page behavior.
- [x] **Existing file-upload UI** — verified end-to-end during [[braindrive-budgeting]] V1.
### Dependencies
- [[document-processing]] substrate (shipping with [[braindrive-budgeting]] V1 per [[document-processing]] D31).
- [[braindrive-budgeting]] V1 shipped — proves the substrate-consumer pattern.
- Existing Fitness page in working order.
- [[braindrive-repo]] D214 spec-template-as-AI-instructions pattern landed.
- Substrate `doc_type` field ([[D12]] cross-project ask).
### Constraints
- **Privacy/security:** No third-party aggregator ([[D8]]). Medical data sensitive; owner-instance-side only. Inherits [[document-processing]] D13/D14 privacy framing.
- **Cost:** Per-spec cost governed by [[braindrive-models]] D48. Inherited from budgeting.
- **Latency:** Substrate parsing dominates. Fitness page changes don't add meaningful latency.
- **Compatibility:** BrainDrive React chat-only client (current).
---
## Test Strategy
### Test Levels Required
- [x] **Integration** — End-to-end on substrate output: parsed lab/note file → existing fitness interview weaves context → spec + build-plan reflect it.
- [x] **Property-based** — `doc_type` routing correctness (fitness-relevant docs route to Fitness context; finance/etc. docs trigger US-4 flag).
- [x] **Regression** — US-5 no-docs path: existing fitness flow output is unchanged when no health docs are uploaded.
- [x] **E2E (DW dogfood)** — DW's real fitness goals + any labs / doctor's notes he can pull from his patient portal. One real owner, one coherent picture.
- [x] **Harness extension** — Katie correlated fictional fitness fixture extending [[braindrive-budgeting]] D26 to include health docs (Katie persona + Katie goals + Katie's plausible labs + Katie's family/life context all consistent). Extends the shared harness per [[braindrive-repo]] D211 / D197 — no harness re-architecture.
### Verification Approach
- **Agent self-verification:** Integration suite runs Katie fixture through the full flow and asserts (a) spec + build-plan include health context as expected, (b) out-of-scope upload triggers US-4 flag, (c) no-docs path matches existing Fitness page baseline.
- **Human verification (Dave W):** Walks through the full flow on his own real goals + uploaded labs; confirms (a) plan-quality parity with ChatGPT-as-coach baseline, (b) health context is woven sensibly, (c) the disclaimer + voice feel right. [[D11]] subjective trust criterion.
- **Production monitoring:** None needed for V1 dogfood (single owner, single machine).
### Baseline Impact
- **Always-run checks affected:** Existing fitness page test suite (regression protection per US-5). Existing budgeting test suite (cross-project — `doc_type` substrate change must not break per-transaction `type` field).
- **Additional checks triggered:** Health-doc-routing tests (US-4). One-time disclaimer trigger test (US-6).
- **Global properties affected:** None outside the Fitness page surface + substrate `doc_type` field.
---
## Security Considerations
### Risk Level
- [x] **Low** (in BrainDrive's overall risk model) — No new auth, no new external network surface, no new third-party APIs.
- [x] **Higher than budgeting at the data-sensitivity layer** — medical data is more sensitive than financial. Mitigation: same architecture (data stays on owner's instance per [[D8]]), but explicitly named in spec because owner perception of risk is higher.
### Threat Assessment
- **User input:** Uploaded medical PDFs/images (substrate handles validation); conversational text. No injection vectors beyond substrate's existing concerns.
- **Code execution:** None.
- **Data sensitivity:** Medical — high. Mitigation: stays on owner's BrainDrive instance ([[document-processing]] D13/D14).
- **Network surface:** None new. Substrate handles the model API call.
- **Blast radius:** Limited to owner's BrainDrive instance. If device compromised, medical files are visible — same risk as any memory file.
### Required Mitigations
- [x] Substrate's existing privacy guarantees inherited unchanged.
- [x] Spec + build-plan never include MRN, SSN, account numbers, or full PANs (substrate strips; consumer is downstream).
- [x] One-time onboarding disclaimer ([[D6]]) explicitly names medical-data sensitivity AND clinical-decision boundary.
- [x] No PHI in the Katie harness fixture (Katie is fictional).
---
## Safety & Disclaimer
### Voice ([[D3]])
**Knowledgeable friend who speculates carefully.** See US-7 acceptance rubric for OK / NOT OK examples.
### Disclaimer surface ([[D6]])
1. **One-time onboarding** on first health-doc upload to the Fitness page:
> *"BrainDrive Fitness is your knowledgeable friend, not your doctor. The labs and notes you share help BrainDrive shape a fitness plan grounded in your real situation. Always discuss significant changes — especially anything involving medication, diagnosis, or symptom management — with a clinician. Your data stays on your machine."*
Acknowledged once. Not re-shown on subsequent uploads.
2. **Woven into spec + build-plan language** — the existing AI-generated spec + build-plan include safety beats at the right moments (e.g., a goal touching a constraint may include *"discuss the plan with your doctor before starting if you haven't recently"*).
3. **Per-conversation friction: minimal.** No per-response footers. The knowledgeable-friend voice carries the disclaimer naturally.
**Wording ownership:** DW edits the draft above before V1 ship ([[Q1]]).
---
## Explicit Boundaries
> **For AI Agents:** These boundaries define what is OUT OF SCOPE for this work. Do not modify, touch, or refactor anything in these areas.
### Do Not Modify
- [ ] **The existing Fitness page itself** — agent.md, spec template, build-plan template, interview flow. Only add the health-doc-aware extensions; do not rework what exists.
- [ ] **The existing fitness interview shape** — goal taxonomy, multi-goal handling, edit flow, conflict-handling between goals (this V1 only adds health-context-conflict surfacing in US-3).
- [ ] **BrainDrive Model routing** — substrate concern.
- [ ] **Substrate output file format** — fitness page consumes; doesn't reshape.
- [ ] **Other project pages** (Finance, Resume, etc.) — Fitness only.
- [ ] **Authentication, authorization, user identity.**
- [ ] **The BrainDrive system prompt at L2** ([[braindrive-repo]] D201).
### Do Not Introduce
- [ ] **FHIR / Whoop API / Oura API / any third-party-data SDK** — anti-differentiator ([[D8]]).
- [ ] **Symptom triage / differential diagnosis logic** — safety boundary ([[D3]]).
- [ ] **A standalone Health page-product** ([[D1]]).
- [ ] **`fitness/health-context.md` as a separate V1 artifact** — health context lives in existing spec + build-plan.
- [ ] **New UI components.**
- [ ] **Per-response disclaimer footers** ([[D6]] — one-time only).
### Out of Scope (Even if Related)
- [ ] **Refactoring [[document-processing]] substrate beyond the `doc_type` field** ([[D12]]).
- [ ] **General-purpose advisor voice improvements** — BrainDrive personality work elsewhere.
- [ ] **Re-shaping the existing Fitness page spec/build-plan template** beyond adding health-doc-aware guidance.
---
## Open Questions
See [[open-questions.md]] for the canonical list.
- [ ] **Q1** — Wording of the one-time onboarding disclaimer ([[D6]]). DW edits before V1 ship.
- [ ] **Q2** — Per-doc `doc_type` classification — substrate prompt extension; DJ folds into T-619.
- [ ] **Q3** — Confirm path where substrate writes uploaded health docs under the Fitness page directory.
- [ ] **Q4** — Stale-doc handling (>2 years old): flag and ask the owner, or use silently?
- [ ] **Q5** — Should the spec output reference specific competing apps for use cases BrainDrive doesn't cover (e.g., "for daily logging, MyFitnessPal handles this well")?
---
## Success Definition
### V1-Shippable Bar ([[D11]] — mirrors [[braindrive-budgeting]] D25)
This V1 does NOT merge to main until it meets the same conversational-form standard DJ has used for every other BrainDrive feature.
**Three gates must pass before handoff:**
1. **Conversational-form standard met** — health-doc ingestion is woven into the existing fitness interview, not bolted on as a separate ceremony. The voice ([[D3]]) holds in the moments health context surfaces. The disclaimer ([[D6]]) feels right.
2. **Test harness end-to-end** ([[braindrive-repo]] D211 + [[D11]] Gate 2) — automated harness drives the full Fitness flow with Katie's correlated fixture **including health docs**, no human-in-the-loop. Extension of the existing harness, not a re-architecture.
3. **Smell-test discipline** ([[dev-system]] [[D25]] analog) — DJ runs the feature through its primary user flow once before handoff.
### Owner-Facing Success Criteria
When this V1 is complete, **Dave W will be able to:**
1. Start the existing fitness interview on the Fitness page (no change to how that begins).
2. State his real fitness goals.
3. Be prompted for health docs when his stated goals warrant it.
4. Upload his real labs / doctor's notes through the existing upload UI.
5. See the resulting spec + build-plan reflect that health context sensibly (knowledgeable-friend voice; not over-conservative; not diagnostic).
6. (On first upload) See the one-time onboarding disclaimer.
7. (Later) Upload a new lab and receive a proactive *"here's what changed — want to update your spec + build-plan?"* prompt.
8. Trust the resulting fitness plan enough to either follow it or use it as a starting point with his clinician.
V1 is **specifically not done** until the three gates pass AND DW's subjective trust holds.
---
## Changelog
| Date | Change | Reason | Source | Decision |
|------|--------|--------|--------|----------|
| 2026-05-20 | Initial draft | `/feature-spec` after `/interview` + `/landscape` | This session | D1–D15 (early framing) |
| 2026-05-20 | Major reframe — narrowed scope from "build Fitness page" to "add health-record ingestion to existing Fitness page" | DW correction: Fitness page already exists; we're adding health-doc ingestion the same way budgeting added statement upload to Finance | This session | D1 reframed; D6/D7/D14/D15 removed (those concerns are existing Fitness page invariants, not ours to invent) |
## Conversation References
| Date | Source | Topics |
|------|--------|--------|
| 2026-05-20 | Dev call (DW + DJ) — transcript | Build sequence, model swap, project-sharing, "health is next" framing | [transcript](../../../transcripts/2026-05/2026-05-20-dev-call-google-flash-test-harness-share-feature-dave-w-dave-j.md) |
| 2026-05-20 | `/interview` (Claude + Dave W) | 5 rounds covering persona, use case, voice, cross-context, day-1 flow, file shape, re-upload, ship bar, spec sections, conflict handling, doc storage, disclaimer, edit flow, invariant, out-of-scope upload, multi-goal | This conversation |
| 2026-05-20 | DW reframe message | Fitness page already exists; this work adds health-record ingestion as the new capability | This conversation |
---
## Approval
- [ ] Reviewed by: _______________
- [ ] Date: _______________
- [ ] Ready for Planning: [ ]
---
*Next: Review with DJ + DW (2026-05-21 AM). Once reviewed, run `/plan` to generate `build-plan.md`.*