Sports Coach

About

Built into the sports-data app, this coaching system replaces a human coach with a structured knowledge layer drawn from years of documented training history. The system combines a static knowledge base covering coaching methodology, race calendar, athlete profile, and session library, with live performance data from Strava, WHOOP, and intervals.icu, and surfaces it through three tabs: a training calendar, a periodisation view, and a direct chat with Fred, an AI coach running on Claude Sonnet.

The story

After two years into a coaching relationship built around specific cycling objectives, the collaboration with my coach had run its course. The programming was good, the progression was real. But the cost had become significant and the rhythm had plateaued into a comfortable routine that was no longer pushing forward.

The question then was not whether to find another coach. It was whether the best parts of the training plan I followed in previous years could be preserved, and improved, by building something different. The structure of training blocks and weekly sessions was worth keeping. The time saved by not having to design the programme yourself was worth keeping. What a human coach could not provide was the ability to handle multiple data sources simultaneously and explain every programming decision in full, at any level of detail.

Building the knowledge base

Before a single line of code was written, the work was documentation. Over two years of training from my recent objectives were extracted and structured into a folder of Markdown files. The process was deliberate, taking several hours across multiple sessions, closer to a formal onboarding than a quick reference document. Previous experience as a competitive athlete and as a trainer made it possible to articulate what the methodology actually was, including the parts that had never been written down before.

coach/
├── context.md              # Training framework, data sources, historical performance, expectations
├── calendar.md             # Race calendar — A/B/C objective hierarchy across the season
├── persona.md              # Fred's identity, voice, knowledge scope, and explicit guardrails
├── athlete-profile.md      # Deep motivations, psychological profile, training preferences
├── questions.md            # Coach-athlete calibration questionnaire
├── workflow.md             # How plan updates flow between Fred, Claude Code, and the app
├── history/
│   ├── complete-blocks.md  # 19 training blocks (2 years) with session details and rationale
│   ├── session-library.md  # Full session library — intervals, zones, progressions
│   ├── cycling-sessions.md # ~250 cycling sessions with RPE and normalised power
│   └── running-prep.md     # Running preparation history
└── blocks/
    ├── periodisation.md    # Planned blocks with rationale — feeds the Periodisation tab in the app
    └── plan-h2-2026.md     # Detailed plan for H2 2026, session by session

Each file serves a distinct function. persona.md describes what Fred knows, and also specifies what he must not do, such as prescribing a taper like for pro athletes, fixating on a single daily recovery reading, suppressing training sessions without a solid reason. These are explicit guardrails written into the file. The restrictions matter as much as the knowledge. context.md holds the reasoning layer: coaching philosophy, training principles, the logic of each block type. The operational data (sessions, dates, power targets) lives separately in a SQLite database. The distinction is deliberate: structured data goes where it can be queried, natural language goes where it can be read, by a human or a model.

The folder has two levels of historical depth. history/ is backward-looking, the record of what was done and how it performed. blocks/ is forward-looking, the plan being built and the reasoning behind it. Keeping them separate makes it straightforward to update the plan without disturbing the reference material.

Writing these files changed more than the system. Going back over several years of blocks to understand the ordering and the progression patterns that had consistently worked: much of the logic that had been applied but never named became visible for the first time. The documentation was as much an audit of previous coaching relationships as a foundation for what came next.

How Fred works

Every time Fred receives a question, two layers of information are available to him.

The first is what he already knows: the Markdown files loaded as a cached context block via the Anthropic prompt cache. That knowledge does not change between conversations. It is always there.

The second is what just happened: current fitness load from intervals.icu, WHOOP recovery trends for the past 7 days, recent Strava sessions with actual power output and perceived effort, the next 6 weeks of planned sessions from the database, and any journal notes from the app.

Think of a doctor who already knows your full medical history. Before your appointment, they have read your file. When you walk in, you tell them how the past week went. The stable knowledge is there permanently. The current moment is injected fresh. Fred works the same way: the Markdown files are the file the doctor knows by heart. What changes daily is pulled right before you speak. Stable things are stored at their natural frequency, once. Current data is pulled at its natural frequency, always.

The three tabs

Calendar replaces TrainingPeaks. A monthly grid shows past and upcoming sessions, colour-coded by type and intensity, with a weekly summary panel on the right covering distance, duration, and training load. Completed sessions pull from Strava. Upcoming sessions come from the SQLite database on the VPS. Sessions can be moved or deleted directly in the app, and any changes are noted in the Journal so Fred sees them in context. The app does not duplicate session details: it redirects to Strava for anything deeper. The goal was to surface existing tools where they are relevant, not to replace them.

Periodisation makes the plan legible. Each training block appears in sequence from the current one through the full planning horizon, with its duration, its goal, and its sessions. The reasoning is written out: why this block now, why this sequence, what it builds toward. The full arc of a season is visible in one place for the first time.

Fred is the tactical interface. Quick prompts cover the most common questions: current form, readiness for the next objective, the week’s programme, what the next block is building toward. Responses are grounded in the numbers. When the question is “am I on track for my next race?”, the answer references the fitness load delta versus the previous year, the current training stress balance, the power from recent sessions, and the sessions that remain before the event. Fred can also explain every choice in full and at any level of detail, in a way the paid coaching relationship did not allow.

Consultative vs executive

Fred and Claude Code serve different functions.

Fred reads, reasons, and advises. He cannot modify the plan files, commit a change to Git, rebuild and deploy the app, or update his own system prompt. He is a counsellor without a pen.

Claude Code does all of that. It can rely on Fred to propose that a block should be adjusted, then turn that proposal into updated files, a redeployed app, and a committed change.

Fred now has the full methodology, the history, and the race calendar. Claude Code has write access. Keeping reasoning and execution in separate interfaces means no unreviewed change reaches the plan.

First test: GF Ventoux 2026

The first meaningful test of a race plan built entirely by the system was the GF Ventoux 2026 on 6 June, a 77km race with 2,100m of climbing. The same event had been run in 2025.

In 2026, the AI produced a section-by-section breakdown of the 2025 race, compared the fitness and freshness profiles across both seasons, and identified that despite 23% less training volume in the build, arriving fresh rather than fit was the right strategy. The plan was followed. The result was a 5% improvement in average power output and a 17th-place finish out of over 500 starters. For an athlete with several years of competitive experience at similar events, that margin is significant.

Honest limits

The system works because of what preceded it: years of competitive experience, a clean and consistent dataset, and prior coaching that established the methodology being documented. It is not a shortcut for someone starting from nothing. The preparation time is real, the domain expertise required is real, and the ongoing work of auditing outputs and updating files as the season evolves is what keeps it accurate over time.

Fred will also occasionally over-index on a single data point and needs to be redirected toward the broader trend. Getting the guardrails right is an iterative process, not a one-time configuration.

A retrieval layer over the plans directory is in progress. The current implementation loads the full knowledge base as a static cached context block. A RAG layer will allow Fred to surface specific session details and historical references on demand without loading the full archive at every request.

Why it matters professionally

The pattern this project demonstrates applies directly in a RevOps or Systems context: take a domain with accumulated expertise, structure that knowledge deliberately, connect live operational data to it, and build an interface designed around how it will actually be used.

The system only works because the subject matter was understood deeply first. That is also the most common failure mode in business: deploying an AI layer over generic or poorly structured knowledge produces generic outputs. Specific guardrails, coherent hierarchy across files, and continuous auditing of results are not AI problems. They are systems design problems. The project is never truly finished. It evolves as the season does.

The two-tier architecture, with Fred as a reasoning interface and Claude Code as an execution interface, has direct equivalents in a professional context: a sales intelligence layer that surfaces context versus a CRM that records actions, a reporting layer that explains versus a pipeline that transforms. Keeping those concerns separate is what makes each one maintainable.