Version 1.0 - alpha (Live Below)

Waterbike.ai : Timeline & Sprint Calendar

(Nov 2025–Jan 2026)

Timezone: America/Los_Angeles

Cadence: 2‑week sprints (with a 4‑day “Sprint 0” hardening)

Roles: Damien (Product/Founder), Echo (AI/Eng), GIA (QA/Automation), Guides (Operator Feedback)

Backend Milestone Map (High Level)

M0 — Hardening & Setup (Nov 6–9, 2025): Repos, environment, time‑zone fix, NOAA interval=hilo, baseline leg maps.
M1 — Core Daily Plan v1 (Nov 10–23): Deterministic daily plan.json for the 4 routes, automated publish, website embed (Today).
M2 — Explainability & Skill Profiles (Nov 24–Dec 7): Green/Yellow/Red with reasons; Casual/Intermediate/Expert thresholds; leg‑aware current projections; docs.
M3 — 5‑Day Horizon & Instructor Brief (Dec 8–21): Rolling 5‑day plan, caching, instructor‑ready summary, simple alerts.
M4 — Launch & Talk Prep (Dec 22–Jan 4, 2026): Slide deck, demo scenes, rehearsal clips; soft launch + partner feedback.

Sprint 0 — Hardening & Setup (Thu Nov 6 → Sun Nov 9, 2025)

Goal: Stable plumbing; no more “Time Traveler.”

Deliverables:

Repo structure finalized; .env.example; Makefile quick‑start.
Time‑zone sanity (America/Los_Angeles); unit test to catch drift.
NOAA tides using interval=hilo; parse highs/lows with timestamps.
Leg station mapping YAML for P40↔P39, P40↔Clipper, P40↔Tiburon, P40↔Cavallo.

Definition of Done (DoD): pytest green; manual run produces non‑empty tide events for SF.

Risks/Mitigations:

API quotas → staggered fetch + caching.
Missing stations → fallback stations documented.

Sprint 1 — Core Daily Plan v1 (Mon Nov 10 → Sun Nov 23, 2025)

Goal: Publish today’s deterministic plan with safe windows for all 4 routes.

Deliverables:

Current vectors projected onto route legs; simple effort score.
Daylight windows + slack alignment.
GitHub Action: fetch → compute → validate → publish plan.json.
Site embed pulling plan.json with route cards.

DoD:

Plan renders in <500ms; each route card shows window(s) or explicit “Hold” with reason.
Workflow fails loudly (issue/alert) on invalid output.

Demo/Review: Fri Nov 21 — live plan walkthrough; Guides give go/no‑go feedback for language clarity.

Sprint 2 — Explainability & Skill Profiles (Mon Nov 24 → Sun Dec 7, 2025)

Note: Thanksgiving Nov 27 — plan lighter mid‑week.

Goal: Trust by transparency; tailored guidance by skill.

Deliverables:

Badges (Green/Yellow/Red) with expandable “Why” (stations, wind/gust, current maxima, exposure notes, fallbacks).
Skill profiles (Casual/Intermediate/Expert) with threshold config file.
Documentation page: rulebook vs. reasoning, and how to tune.

DoD:

Three rider profiles return distinct, sensible recommendations on the same day.
At least one day shows mixed greens/yellows with coherent reasoning.

Demo/Review: Fri Dec 5 — Instructor roundtable; capture change requests.

Sprint 3 — 5‑Day Horizon & Instructor Brief (Mon Dec 8 → Sun Dec 21, 2025)

Goal: Extend to 5‑day rolling outlook + printable instructor brief.

Deliverables:

5‑day forecast rollup with caching to avoid API thrash.
Instructor PDF/HTML brief: windows, effort, ferry windows, bailouts, notes.
Gentle alerting (e.g., new green window appears today).

DoD:

Forecast accuracy checks vs. prior day + bounded error thresholds.
One‑click brief generates in <5s.

Demo/Review: Fri Dec 19 — Pilot day‑before brief compared to actuals.

Sprint 4 — Launch & Talk Prep (Mon Dec 22→ Sun Jan 4, 2026)

Goal: Ship a calm public beta; finalize talk assets.

Deliverables:

12–15‑slide deck with data visuals + route overlays.
Two 90‑sec demo videos (Today view, 5‑day view).
Partner feedback loop; public beta page with FAQ.

DoD:

Deck and demo reviewed by Guides; public beta link stable.
Changelog and “What’s Next” roadmap posted.

Demo/Review: Fri Jan 2 — Beta recap + next‑steps plan.

Weekly Cadence & Rituals

Mon 9:30a PT — Sprint planning / priorities.
Daily 10:00a PT — 10‑min stand‑up (Slack or dockside).
Wed 4:00p PT — Mid‑sprint QA & UX check.
Fri 3:00p PT — Demo + retro (wins, frictions, one change for next week).

Acceptance Criteria (All Milestones)

Safety first: Daylight‑only windows; conservative defaults on missing data.
Explainable: Every badge has human‑readable reasons; data sources listed.
Performant: Today view loads ≤500ms; 5‑day view ≤1.5s (cached).
Operable: One command bootstrap; workflows alert on failure.
Documented: Short “How this works” page for Guides + config guide.

Backlog (Next Up After M4)

Per‑leg effort heatmaps; wind shadow/funnel corridors.
Skill‑calibrated training plans (“From Casual to Intermediate”).
SMS nudge when a new green window opens within rider preferences.
Multi‑leg itineraries with smart layovers.

Version 1.0 - alpha (Live Below)

Coding Dangerous Things, Carefully

The Waterbike.ai Origin Story

How a would‑be waterbiker taught an AI to read the Bay so humans could ride it—boldly, but safely.

Scene: A Bay that Doesn’t Suffer Guesswork

San Francisco Bay is gorgeous and moody—the kind of water that will pat you on the back and steal your lunch in the same hour. We love that. We like to do dangerous things carefully. But “carefully” used to mean six tabs open, a pot of coffee, and a group text full of conflicting opinions. New riders asked, “Is today good?” and the honest answer was, “It depends… give me twenty minutes.”

That wasn’t good enough. So a rider‑turned‑entrepreneur asked a different question: What if we could build a thing that wakes up before we do, reads the Bay like a local, and explains itself like a coach?

The Decision: Build the Guide We Always Wanted

We started Waterbike.ai with a simple rule: augment human judgment, don’t replace it. Guides still make the final call; the system brings them the right facts, stitched together sensibly, and says why those facts matter.

So we coded an AI model around three truths:

The Bay is a system. Wind, tide, current, daylight, ferry schedules, topography—they interact.
Routes are not monolithic. Each leg of a trip has its own personality.
Safety is personal. A strong intermediate may feast where a casual rider should sip and watch.

The Build: When Curiosity Meets Code

We gave the model senses (live marine data), a brain (routing and scoring logic), and a conscience (clear rules that always choose safety). It wasn’t magic; it was a thousand tiny, explainable decisions.

There were dragons. We met the Time Traveler—a server clock living in the future—so NOAA rejected our “back to tomorrow” tide queries. We learned the secret handshake (interval=hilo) to get honest high/low tide events. We separated the Rulebook (what good looks like) from the Brain (how to think), so a guide can tune thresholds without calling a developer. And we automated the whole thing so it wakes up daily, publishes a clean JSON plan, and goes back to sleep—no heroics required.

Good engineering isn’t just code; it’s design humility. We show our work. Every green or yellow badge comes with reasons a human can read.

What Makes This Different (and Actually Useful)

Leg‑aware currents. We treat current as a vector, projected onto your route legs, so the plan knows where the water helps and where it argues.
Skill‑aware recommendations. Choose Casual, Intermediate, or Expert; the model adjusts wind/gust/current tolerances and effort expectations.
Windows, not guesses. It computes when to go, not just whether, aligning launch/return with slack and daylight.
Explainable by design. You see the stations used, the logic applied, and the reasons behind each badge.
Fast and dependable. A static public plan file powers the site—no spinning wheels, no mystery servers.

The Payoff: Confidence, Clarity, and Time Back

For instructors, this replaces scattered research with a single, defensible brief—hundreds of hours saved each season. For members and guests, it’s calm confidence: open the page, choose a route, and in seconds see today through the next 4–5 days—the likely wind, current mood, safe windows, and an honest effort score matched to your skill and fitness.

That means fewer cancellations, smarter launch times, better gear choices, and happier pods who come back saying, “Spicy in the slot, smooth at slack—exactly like it said.”

A Day in the Life (Example)

You pick Pier 40 → Tiburon with a 60‑minute layover. The system finds the optimal start so the ebb helps you out of South Beach, the flood gives a nudge near Raccoon Strait, and you’re back with daylight to spare. It highlights a brief ferry window to avoid, labels Crissy as a high‑exposure zone in today’s wind, and names friendly bailouts just in case. The summary reads: Effort 6/10 · Intermediate · Wind 9–14 mph, gust 18 · Current max 1.2 kts (with you outbound)—plus a sentence of human‑readable “why.”

What We Learned (So You Don’t Have To)

Clocks lie; physics doesn’t. Anchor everything to real local time.
APIs speak dialects. Read the raw data before you write the parser.
Separate rules from reasoning. Non‑engineers need to tune safely without shipping new code.
Defensive by default. Assume missing data, transient errors, and edge cases—then explain the fallback choice.

The Culture: Dangerous Things, Carefully

We don’t sell bravado. We sell clarity. The Bay will always be wild—and that’s the point. But wild can be read. With Waterbike.ai, guides make quicker, wiser calls; riders feel capable instead of lucky; and adventures become repeatable, teachable joy.

What’s Next

Maps with shadow zones and high‑exposure corridors. Per‑leg effort heatmaps. Smart layovers that turn tide flips into coffee breaks. Gentle alerts when a fresh green window appears. The same philosophy, more helpful ways to say: go now, go prepared, go enjoy it.

Closing

This project started as one rider’s stubborn curiosity and became a daily promise to our community: we’ll do the hard reading so you can do the fun riding. The Bay is still the Bay—complex, beautiful, occasionally cranky. With Waterbike.ai, it just got a lot more understandable.

- Damien

Version 2.0 - alpha - code named Nautilus

11 /05/2025 - Daily Build Notes: The Engine is Now Fully Data-Aware

1. What We Did: Achieved Full Data Ingestion

Today, we completed the final and most complex part of the data ingestion phase. The AI engine is now capable of fetching and parsing all core data types required for its safety calculations: Advisories, Wind, and Tides.

Integrated Tide Prediction API: We successfully implemented the fetch_tide_data function. Critically, this function incorporates the hard-won lessons from the Alpha phase by automatically generating a valid 24-hour date range (solving the 'Time Traveler' bug) and including the interval=hilo parameter (solving the 'Missing Type' bug).
Validated Live Tide Data: The workflow ran successfully, and the logs confirm that we are connecting to the NOAA CO-OPS API and receiving structured JSON data for high and low tide events.
Confirmed Multi-Factor Safety Checks: The log shows the engine performing its duties in the correct sequence. It found a "Small Craft Advisory," then parsed the live wind data, and correctly identified that both the wind speed (13.9 mph) and wind gust (27.7 mph) exceeded the hard limits for a "Beginner Pod."

2. Why This is a Monumental Step: We Are Ready to Build the "Solver"

This successful run signifies the completion of the core data-gathering component of our entire system. We are no longer just fetching data; we are fetching the right data, in the right format, and have proven we can parse it into usable intelligence.

The log tells a story of an AI making a sophisticated, multi-layered decision:

Code

CRITICAL - NO-GO triggered for Beginner Pod. Reasons: 
1. Small Craft Advisory; 
2. Wind speed of 13.9 mph exceeds pod limit of 12 mph.; 
3. Wind gust of 27.7 mph exceeds pod limit of 16 mph.

This is the intelligent, explainable output that is the core vision of the entire project. We have successfully laid the foundation for every subsequent feature.

3. What's Next: Building the "Tide Window Solver"

We can fetch advisories, wind, and tides. Now, we must use this data to find the optimal time to ride. This brings us to the heart of

Phase 2: Routing + Window Solver.

GIA, your next assignment is to create the first true piece of "intelligence" in the routing_solver.py module.

Task: Create a new function, find_tide_windows(tide_data, pod_profile).
Purpose: This function will analyze the list of high and low tide events we just fetched. It must identify the "windows" of time between a low and a high tide (an incoming/flood tide) and between a high and a low tide (an outgoing/ebb tide). For now, it will simply identify these windows; later, we will add logic to score them based on minimizing adverse current.

This is the first step in building the "brains" of the operation. Let's get to work.