# Spec: Fitness Journal

> **Purpose:** Page-specific delta spec for the Fitness journal — a **built-in BrainDrive journaling feature** (the page-journal pattern), not a child app. Shared journal behavior is defined in [`../../foundation/page-journal/spec.md`](../../foundation/page-journal/spec.md).
> **Status:** Slimmed 2026-06-12 after shared Page Journal spec was created; reframed 2026-06-25 off the child-app model (built-in feature, not a child app) per D257/D265.

**Owner:** Dave W (product) / Dave J (build)
**Parent surface:** [`../spec.md`](../spec.md)
**Shared journal spec:** [`../../foundation/page-journal/spec.md`](../../foundation/page-journal/spec.md)
**Roadmap view:** [`operations/planning/fitness/roadmap.md`](../../../../../operations/planning/fitness/roadmap.md)
**Build handoff:** Dave J creates downstream requirements/build/test artifacts through the software-factory build workflow after prioritization accepts the work for build.

---

## What This Spec Owns

Fitness Journal is the built-in journaling feature for the Fitness page (the page-journal pattern, used directly by the Fitness page — not a child app the page routes to). It inherits the shared Page Journal contract. This spec only defines what is unique to Fitness:

- fitness, health-adjacent, body, habit, energy, recovery, and adherence context;
- pattern reflection for progress, blockers, plan mismatch, and owner agency;
- health-adjacent safety boundaries;
- separation from food tracking, workout tracking, wearables, dashboards, and medical care;
- Fitness-specific scenario and test coverage.

Fitness Journal is not the Fitness page itself. Fitness owns goals, current state, constraints, success criteria, and the plan. Fitness Journal owns owner-entered observations that keep the Fitness coach current after the initial interview/spec/plan session.

---

## Fitness-Specific Scope

An owner can use Fitness Journal to capture:

- food, movement, workout, energy, sleep, recovery, adherence, blocker, and progress notes;
- follow-up context after the Fitness plan is created;
- plan friction, schedule/body/energy changes, and owner-observed patterns;
- health-adjacent context when it helps the Fitness plan stay grounded;
- plain-language reflections that do not require a full tracker.

Fitness Journal must not become:

- a food database, barcode scanner, macro/calorie engine, or meal-photo analyzer;
- a workout tracker, workout timer, exercise library, training platform, or GPS tracker;
- a wearable, Apple Health, Garmin, Health Connect, or device-import integration;
- a medical diagnosis, treatment, rehabilitation, lab interpretation, or clinical advice product;
- a passive ingestion system;
- a gamified streak system, leaderboard, or social fitness surface.

---

## Fitness Starting Positions

| Starting Position | What Fitness Journal Must Recognize | Quality Bar |
|---|---|---|
| Quick daily note | Owner wants to record what happened without structure. | Captures a concise dated entry with source/page context and no forced tracker fields. |
| Food/movement detail | Owner shares food, workout, movement, energy, recovery, adherence, blocker, or progress context. | Stores owner-provided detail clearly without inventing metrics or precision. |
| Pattern / plateau review | Owner asks what the journal shows, why progress is not matching the plan, or what may be getting in the way. | Reviews history for adherence, recovery, schedule, food/movement consistency, stress/travel, plan difficulty, and blockers; frames observations as hypotheses. |
| Plan mismatch | Entries suggest the Fitness plan no longer fits real life. | Asks before updating Fitness `spec.md` or `plan.md`. |
| Health-adjacent note | Owner mentions injury, symptoms, medication, diagnosis, labs, pregnancy, or medical care. | Stores owner-provided context safely while avoiding diagnosis, treatment, or medical advice. |
| Task/follow-through | Entry creates a concrete commitment. | Captures the commitment in the entry's `Follow-up → Proposed task` field; routing to the to-do list arrives V.1.1. |

---

## User Stories

### FJ-1: Add A Fitness Journal Entry

```gherkin
Given the owner shares a fitness follow-up note
When BrainDrive identifies it as journal-worthy
Then BrainDrive writes a dated entry to Fitness `journal.md`
And preserves source conversation and Fitness page context
And confirms what was saved and where
```

### FJ-2: View Or Correct Fitness Journal Context

```gherkin
Given Fitness Journal entries exist
When the owner asks what they have logged or asks to correct a prior entry
Then BrainDrive reads the Fitness journal state
And summarizes or updates only the intended entry
And preserves unrelated journal content
And does not invent logs, metrics, or adherence scores
```

### FJ-3: Surface Fitness Patterns And Blockers

```gherkin
Given multiple Fitness Journal entries exist
When the owner asks how things are going or BrainDrive detects a relevant pattern during a follow-up session
Then BrainDrive reviews entries over time
And surfaces progress signals, adherence patterns, blockers, or plan mismatches as hypotheses
And asks the owner whether the pattern feels true before updating Fitness `spec.md` or Fitness `plan.md`
```

### FJ-4: Keep Pattern Reflection Coach-Like

```gherkin
Given weight loss, workout consistency, energy, recovery, or adherence is not matching the plan
When BrainDrive reflects on the journal history
Then it avoids shame, diagnosis, commands, or certainty
And explains the observation in plain language
And offers to explore likely blockers or plan adjustments with the owner
```

### FJ-5: Stay Inside Health Boundaries

```gherkin
Given the owner logs health-adjacent context
When BrainDrive stores or summarizes the entry
Then it treats the information as owner-provided context
And avoids diagnosis, treatment, medication, or clinical claims
And routes safety-critical or medical questions to appropriate professional-care language
```

---

## Data And Routing Delta

| Artifact | Rule |
|---|---|
| `documents/fitness/journal/journal.md` | Owner-entered Fitness follow-up history using the shared journal format |
| Fitness `spec.md` | Current Fitness goals, current state, constraints, assumptions, and success criteria |
| Fitness `plan.md` | Ordered Fitness next steps, milestones, active plan, and plan status |
| To-do list (built-in feature, V.1.1) | Concrete commitments — in V.1 these stay in the journal entry's `Follow-up → Proposed task` field; routing to the to-do list arrives V.1.1 (see Page Journal spec §Journal ↔ To-Do List Handoff) |
| `me/profile.md` | Stable cross-project owner facts only after confirmation |
| Future external tool calling (V.1.1) | Nutrition tracker, workout tracker, wearable import, health records, or dashboards arrive as future **external tool calling** (V.1.1, per D257), not built-in apps |

---

## Test Focus

- Fitness Journal follows the shared Page Journal create/view/correct/pattern/adjustment flow.
- Fitness `spec.md` / `plan.md` updates are owner-approved and concise.
- Pattern reflection surfaces progress, blockers, adherence signals, and plan mismatches as hypotheses.
- The system avoids shame, overconfidence, invented metrics, and medical claims.
- Health-adjacent context remains owner-provided context, not diagnosis or treatment.
- Tracker, wearable, medical, social, and dashboard scope does not enter V.1.

---

## Success Definition

Fitness Journal V.1 is done when:

1. The owner can return after the initial Fitness interview/spec/plan and BrainDrive can run a useful follow-up session.
2. The owner can create, view, and correct journal entries conversationally.
3. BrainDrive can review journal history to surface progress signals, blockers, plan mismatches, and owner-calibrated hypotheses.
4. Parent Fitness spec/plan updates are owner-approved and concise.
5. The journal follows the shared Page Journal spec and BrainDrive memory architecture.
6. Health-adjacent boundaries hold.
7. The harness can run and score the Fitness journal flow.

The work is not successful if Fitness Journal becomes a full tracker platform, makes medical claims, silently updates parent artifacts, overwrites owner entries, or reflects patterns in a shaming or overconfident way.

---

## Changelog

| Date | Change | Reason | Source | Decision |
|---|---|---|---|---|
| 2026-06-30 | Deferred to-do list routing to V.1.1; in V.1 concrete commitments stay in the journal entry's follow-up field. | [[braindrive-repo]] D272 moved the to-do list to V.1.1; journaling ships first in V.1. | DW | Confirmed |
| 2026-06-25 | Reframed off the child-app model: this is a built-in BrainDrive feature, not a child app. | Propagation of D257/D265 | DW direction | Confirmed |
| 2026-06-12 | Slimmed spec to page-specific delta and moved repeated journal behavior to shared Page Journal spec. | Avoid repeating the same journal contract across every page-specific spec. | DW review | Draft |
| 2026-06-12 | Added pattern reflection and coaching insight requirements. | Journal history should help BrainDrive surface useful progress signals, blockers, and plan mismatches as owner-calibrated hypotheses. | DW review | Confirmed |
| 2026-06-11 | Created Fitness Journal child-app spec for Phase 2 V.1. | V.1 spec coverage review. | DW review | Confirmed |

## Approval

- [x] Reviewed by: Dave W
- [x] Date: 2026-06-30
- [x] Ready for Planning: [x]