Athlete daily log consolidation proposal

Status: Draft, pre-implementation review
Date drafted: 2026-04-13
Scope: Athlete-scoped logging, note storage, and legacy log migration

1. Purpose

This proposal defines a simpler logging model for athlete operations. The goal is to stop creating multiple overlapping daily log files across coordinator, specialist, intake, and nutrition folders, and replace that pattern with one canonical daily log per athlete per day.

The target state is:

• one canonical daily log file per athlete: athlete/logs/daily/YYYY-MM-DD.md
• automatic file creation when a write is needed and the day file does not yet exist
• one shared ## Activities section covering all logged athlete sessions for the day
• one top-level ## Coach Luca section and one top-level specialist section per contributing domain
• one shared ## Nutrition section with one time-stamped subsection per nutrition item
• legacy daily log files refactored into the new structure and then retired or archived

Because the current system is athlete-scoped, the practical canonical path should be athlete/logs/daily/YYYY-MM-DD.md, not a global top-level daily-log path outside the athlete root. If a shorter logical name is desired in prompts or tooling, it can be referred to as the athlete's /logs/daily/YYYY-MM-DD.md path inside the athlete root.

2. Problem summary

The current model spreads one day of athlete state across too many files. For Sidney, a single day may exist in several or all of the following places:

• coordinator internal team report: athlete/team-reports/daily/
• athlete-facing morning note: athlete/athlete-notes/daily/*-morning.md
• athlete-facing evening note: athlete/athlete-notes/daily/*-evening.md
• endurance daily log: athlete/team/endurance/logs/daily/
• recovery daily log: athlete/team/recovery/logs/daily/
• strength daily log: athlete/team/strength/logs/daily/
• nutrition daily log: athlete/team/nutrition/logs/daily/
• nutrition staging ledger: athlete/intake/nutrition-staged-items.md
• routing ledger: athlete/intake/routing-log.md
• cross-date durable nutrition record: athlete/team/nutrition/records.md

This produces three different problems:

1. The same event is written multiple times in slightly different forms.
2. Missing one file does not mean the day is missing, it means the day is fragmented.
3. A human trying to understand one day must manually reconcile several sources.

The 2026-04-12 example makes the problem concrete. That day is represented in:

• athlete/team-reports/daily/2026-04-12.md
• athlete/athlete-notes/daily/2026-04-12-morning.md
• athlete/athlete-notes/daily/2026-04-12-evening.md
• athlete/team/nutrition/logs/daily/2026-04-12.md
• athlete/intake/nutrition-staged-items.md
• athlete/intake/routing-log.md
• athlete/team/nutrition/records.md

At the same time, same-day endurance and recovery specialist daily logs were absent, which shows the deeper issue: the system has many places a day can live, but no single place that must contain the day.

3. Current-state assessment

Based on the current Sidney workspace layout, the logging model is split like this:

Root causes

The sprawl is caused by structure, not by one bad file:

• the system treats internal report, athlete message, specialist note, and nutrition intake as separate storage products
• nutrition has both workflow ledgers and durable records, so the same item is repeated across three or four files
• morning and evening notes are stored as independent documents instead of day-scoped outputs
• the current doctrine assumes one writer per file, which pushes every specialist toward a separate daily file

The last point matters most. A one-file-per-day model conflicts with the current one-owner-per-file rule. If the system moves to a single day file, ownership rules must also change.

4. Proposed target model

Canonical file

For each athlete and date, the system should use one canonical log file:

• athlete/logs/daily/YYYY-MM-DD.md

This file becomes the human-readable source of truth for that day.

File creation rule

If any workflow needs to log data for a date and the daily log file does not exist, the system should:

1. create athlete/logs/daily/YYYY-MM-DD.md
2. write the standard heading and empty required sections
3. append the new content into the correct section

This must be treated as a required behavior, not a best effort.

Activity capture rule

The canonical daily log should also store every athlete activity logged for that date, including rides, runs, endurance sessions, strength workouts, recovery sessions, and any other training events recorded in connected systems or internal planning workflow.

Each logged activity should preserve the key identifiers and evidence references needed for coaching review and later audit, including where available:

• TrainingPeaks activity ID
• activity title and type
• planned versus completed status
• start time and duration
• key activity stats such as distance, TSS, IF, NP, average power, normalized heart rate, elevation, cadence, speed, and workout compliance markers as applicable
• source-system references such as TrainingPeaks workout or activity URLs when stored elsewhere in the workspace
• references to raw files such as FIT, TCX, or related source artifacts when they exist in the athlete data archive
• notes about evidence quality when the activity record is incomplete, delayed, manually confirmed, or inferred from athlete messaging

The activity record inside the daily log should be the human-readable canonical summary for that day, even if raw source files continue to live in the athlete data archive.

Weekly rollup rule

If a weekly summary is still useful, it should become a derived rollup rather than a second primary log:

• athlete/logs/weekly/YYYY-Www.md

The weekly file should summarize and link to the daily logs. It should not be the only place where weekly information exists.

Athlete-message capture rule

When a morning plan or evening summary is sent to the athlete, the canonical daily log should store the exact sent body, verbatim, under the matching communication subsection.

The exact sent body should be wrapped in a ~~~ fenced code block so:

• the original line breaks are preserved exactly
• the saved version is visibly distinct from internal notes or later commentary
• downstream review can verify what was actually delivered to the athlete

If send status, delivery metadata, or internal notes are also needed, they should be written outside the code block so the code block remains an exact copy of the athlete-facing message body only.

5. Proposed daily file structure

Each daily log should follow one consistent structure.

# YYYY-MM-DD

- Athlete: Sidney McGill
- Username: sidney
- Timezone: America/Edmonton
- Last updated: 2026-04-13 16:05 MDT

## Summary

Short integrated day summary, updated by Coach Luca as the day develops.

## Activities

### 09:02 - Road endurance ride

- Status: completed
- Session type: endurance ride
- TrainingPeaks activity ID: 123456789
- Planned workout ID: 987654321
- Source systems: TrainingPeaks, FIT archive
- FIT file: `athlete/data/trainingpeaks/raw/2026-04-13/123456789.fit`
- Duration: 3:00:00
- Distance: 81.0 km
- TSS: 142
- IF: 0.71
- NP: 184 W
- Average power: 167 W
- Average heart rate: 148 bpm
- Elevation gain: 742 m
- Compliance note: completed as planned, pacing smoothness inconsistent in final hour
- Evidence quality: confirmed by athlete message plus activity record

## Coach Luca

- Coordinator decisions
- key athlete-facing outputs sent
- integrated tradeoffs and follow-up

## Endurance

- session interpretation
- training decisions
- execution issues

## Recovery

- readiness notes
- fatigue and sleep flags
- recovery actions

## Strength

- gym notes
- load interactions
- scheduling constraints

## Nutrition

- day-level nutrition interpretation
- fueling risks
- totals or summary when useful

## Nutrition

### Summary

| Time | Item name | Calories | Carbs | Protein | Fats |
|---|---|---:|---:|---:|---:|
| 16:05 | Toast with peanut butter and jam | 265 | 35 g | 7 g | 11 g |
| 19:50 | Chicken, potatoes, squash, and peppers | 565 | 50 g | 49 g | 17 g |
| **Total** |  | **830** | **85 g** | **56 g** | **28 g** |

### 16:05

- Received:
- Consumed:
- Item:
- Source media path:
- Estimated intake:
- Key assumptions:
- Practical implication:
- Status:

### 19:50

- ...

## Messages

### Morning plan

- exact athlete-facing morning message body, verbatim, inside a `~~~` fenced code block

~~~
Good morning, Sidney

**Readiness:**
...

/luca
/recovery
~~~

- send status and delivery metadata live below the code block, not inside it

### Evening summary

- exact athlete-facing evening message body, verbatim, inside a `~~~` fenced code block

~~~
Good evening, Sidney

**Today's session:**
...

/luca
/endurance
~~~

- send status and delivery metadata live below the code block, not inside it

### Same-day inbound highlights

- any materially important athlete messages that changed the plan

## System

- workflow events worth keeping in the day history
- unresolved blockers
- data-source failures such as TP auth issues

## Notes

- general notes that do not belong more specifically under Activities, Coach Luca, specialist sections, Nutrition, Messages, or System

## Open items

- next checks
- unresolved questions
- carry-forward items for tomorrow

This structure keeps the required ## Activities, specialist sections, and ## Nutrition sections while still leaving room for coordinator outputs, operational blockers, general notes, and daily continuity.

6. Ownership model change required

The current doctrine says each file has one owner and one normal writer. That rule is incompatible with a single shared daily log that contains specialist subsections.

This proposal requires a controlled logging mechanism:

• the canonical daily log file remains athlete-canonical
• specialists do not manually write arbitrary content into the file structure in an uncontrolled way
• writes to shared daily sections need to be coordinated through a stable system mechanism
• Coach Luca remains responsible for integrated coaching summary, final organization, and conflict resolution

This keeps one canonical file without opening uncontrolled multi-writer edits across the same Markdown file.

An alternative is section-level ownership inside one file, but that is higher-risk because it creates edit conflicts, ambiguous ownership, and more brittle automation. The exact system mechanism for coordinated writes should be defined in a separate implementation proposal.

7. Mapping from current files to the new daily log

The table below proposes where current content should go.

8. Nutrition-specific design

Nutrition is the area with the most duplication, so it needs explicit rules.

Proposed rule

Each nutrition item should have one canonical human-readable home:

• athlete/logs/daily/YYYY-MM-DD.md under ## Nutrition

Each item should use a separate time subheading:

• ### 16:05
• ### 19:50
• ### 19:50 (2) when multiple items land in the same minute

Daily nutrition summary table

At the top of the ## Nutrition section, the daily log should also maintain a live summary table with one row per logged nutrition item and one final totals row.

Required columns:

1. Time
2. Item name
3. Calories
4. Carbs
5. Protein
6. Fats

Required behavior:

• when a new nutrition item is logged, the item gets both a new detailed ### HH:MM subsection and a new row in the summary table. Link the time in the table to the heading for that nutrition section.
• when an existing item is revised, the matching row in the summary table is updated as well
• the final row always shows the current daily totals for calories, carbs, protein, and fats
• the table should always reflect the same set of logged items that appear below it in the detailed nutrition subsections

This creates two useful views of the same day:

• a quick-scan nutritional summary at the top of the section
• a detailed item-by-item record underneath

What stays with each item

Each nutrition entry should preserve the fields that matter operationally:

• received time
• consumed time or consumed window
• item description
• source media path if any
• estimate
• assumptions
• practical implication
• revision or correction note if later clarified

The table row for that item should preserve the compact daily-summary fields:

• time
• item name
• calories
• carbs
• protein
• fats

What should no longer be duplicated elsewhere

Once the daily log is the canonical human-readable record, the system should stop maintaining both:

• a same-day nutrition log file
• a second narrative durable nutrition record file with the same content

If the system still needs a machine-friendly nutrition ledger for automation, it should be generated from or synchronized with the canonical daily log, not maintained as a separate narrative source of truth.

The logging workflow should update the daily nutrition summary table and recalculate the totals row every time a nutrition item is added or revised.

9. Activity-specific design

Activities need explicit treatment because they are central to coaching interpretation and currently risk being split between TrainingPeaks, data archives, athlete messages, and coordinator notes.

Proposed rule

Each logged athlete activity should have one canonical human-readable home:

• athlete/logs/daily/YYYY-MM-DD.md under ## Activities

Recommended activity entry structure

Each activity should use one subsection with the best available local start time and activity label, for example:

• ### 09:02 - Road endurance ride
• ### 14:30 - Lower-body strength session

Each activity entry should preserve, where available:

• status: planned, completed, skipped, modified, or unconfirmed
• activity type
• title
• TrainingPeaks activity ID
• planned workout ID if applicable
• source-system reference
• FIT, TCX, or related raw-file path in the athlete data archive
• duration
• distance
• TSS
• IF
• NP
• average power
• max power when relevant
• average heart rate
• max heart rate when relevant
• cadence
• elevation gain
• speed or pace where relevant
• indoor versus outdoor context when useful
• compliance or deviation note
• evidence-quality note

Planned versus completed logic

The daily log should support both of these states:

• planned activity exists but completion is not yet confirmed
• completed activity exists with verified or provisional stats

This allows the day file to function through the full day, not only after all source systems have synced successfully.

Raw files versus canonical summary

Raw FIT and related source files should remain in the athlete data archive. The daily log should not duplicate raw data dumps. It should store the identifiers, essential performance summary, and archive references needed to locate the authoritative raw files later.

As with nutrition, activity logging should be handled through the same coordinated daily-log workflow rather than by ad hoc file edits across multiple log locations.

10. Proposed directory reorganization

The athlete root should separate four categories clearly:

Directories that should shrink or disappear as primary log locations

• athlete/team/*/logs/daily/
• athlete/team-reports/daily/
• athlete/athlete-notes/daily/
• athlete/team/nutrition/logs/daily/

Files that should become non-canonical or machine-only

• athlete/intake/routing-log.md
• athlete/intake/nutrition-staged-items.md
• athlete/team/nutrition/records.md

These can either be retired or replaced with a minimal operations ledger if the automation layer still needs append-only workflow tracking.

11. Migration and refactor plan

This should be implemented in phases.

Phase 1: establish the new structure

1. Create athlete/logs/daily/ and athlete/logs/weekly/.
2. Add the canonical daily log template.
3. Define the coordinated write behavior that creates the day file when missing and appends to the correct section.
4. Add activity-ingest support so TrainingPeaks IDs, summary stats, and raw-file references can be appended into ## Activities.
5. Update prompts, skills, and doctrine to treat the daily log as the primary athlete day record.

Phase 2: dual-write during validation

1. For a short validation window, write both the old files and the new daily log.
2. Compare outputs for missing fields, broken ordering, and ownership issues.
3. Confirm that morning notes, evening notes, specialist contributions, activity entries, and nutrition entries all appear correctly in one day file.

Phase 3: backfill current history

1. For each date already represented in current logs, create athlete/logs/daily/YYYY-MM-DD.md if missing.
2. Merge coordinator report content into ## Summary, ## Coach Luca, ## System, and ## Open items.
3. Merge activity evidence from TrainingPeaks-derived notes, daily reports, and data archives into ## Activities with IDs, summary stats, and source-file references.
4. Merge specialist daily logs into their top-level specialist sections.
5. Merge nutrition records into ## Nutrition using consumed-date placement.
6. Merge athlete-facing morning and evening outputs into ## Messages.
7. Preserve media paths, activity archive references, and key provenance fields.
8. Mark migrated files as archived only after verification.

Phase 4: retire legacy daily log creation

1. Stop creating new files under the old daily log directories.
2. Archive old directories under a clearly marked legacy path if historical preservation is required.
3. Update all read-order instructions to point first to athlete/logs/daily/YYYY-MM-DD.md.

12. Weekly logging recommendation

The weekly model should also be simplified.

Recommended rule

• one canonical weekly rollup file: athlete/logs/weekly/YYYY-Www.md
• generated from the daily logs
• no separate weekly team report and weekly athlete note as storage sources

The weekly rollup should contain:

• week summary
• key activity totals and important sessions
• key training outcomes
• readiness and recovery themes
• nutrition themes
• major risks
• next-week carry-forward decisions
• links to the relevant daily logs

13. Other cleanup recommendations

Treat athlete-facing messages as outputs, not as primary logs

Morning and evening notes should be persisted inside the daily log as exact sent-body copies under ### Morning plan and ### Evening summary, each wrapped in a ~~~ fenced code block. If a separate file copy is still needed for delivery tooling, that file should be treated as an export artifact, not a second source of truth.

Keep evergreen notes out of the daily log tree

Files such as coach-notes.md, season planning drafts, race schedule, and travel schedule are not daily logs and should remain outside the new log/ tree.

Keep media separate from logs

Binary media should remain in media directories. The daily log should reference the media path, not absorb binary content or duplicate it elsewhere.

Keep raw activity files separate from logs

FIT, TCX, and similar source artifacts should remain in the athlete data archive. The daily log should capture only the identifiers, summary metrics, and file references needed for review.

Reduce narrative duplication in operations ledgers

If the system still needs routing or staging for automation, keep it minimal and operational. Do not repeat the full athlete-readable nutrition narrative there if the canonical daily log already has it.

Keep implementation details separate from the format proposal

This proposal should define the unified athlete log format and the required content only. The separate design for how the system performs coordinated reads and writes should live in its own implementation proposal.

14. Benefits of this change

If implemented correctly, this change will:

• make one file enough to understand one day
• make one file enough to understand both what the athlete did and how the team interpreted it
• reduce duplicated narrative writing
• make missing information obvious instead of hidden across directories
• simplify daily review for both the operator and Coach Luca
• make migration to other athletes easier because the structure becomes predictable
• make weekly rollups simpler because every week is already composed of standardized daily files

15. Risks and mitigations

16. Recommendation

Approve the consolidation direction with these explicit design decisions:

1. Canonical athlete day log path: athlete/logs/daily/YYYY-MM-DD.md.
2. Canonical athlete week rollup path: athlete/logs/weekly/YYYY-Www.md.
3. ## Activities, ## Coach Luca, the specialist sections that have relevant content, and ## Nutrition are the required operating sections in every daily log.
4. Activity entries should store the best available identifiers, summary stats, and raw-file references, including TrainingPeaks activity IDs and FIT archive paths when available.
5. ## Nutrition should include a live summary table with one row per logged item and a final totals row for calories, carbs, protein, and fats.
6. Nutrition items use one ### HH:MM subsection per item under ## Nutrition.
7. ### Morning plan and ### Evening summary should each store the exact athlete-facing message body verbatim in a ~~~ fenced code block.
8. Separate daily specialist logs, daily team reports, and daily athlete-note files should be retired after migration.
9. Routing and staging should become minimal operational ledgers only if the automation layer still requires them.
10. The daily log should include a ## Notes section for general notes that do not fit a more specific section.

This is a structural cleanup that should materially reduce complexity. It addresses the real problem, which is not only too many files, but too many competing daily sources of truth.