Coach that talks back. Opt-in, on-device, and picky about what it says.
For the first time, your Coach analysis can end with words — a short coaching narrative that reads what happened in your hold and tells you what to work on next. Not a number, not a color bar. Sentences. Written by an on-device Apple Intelligence model, gated behind a hallucination-check that filters invented numbers before they ever reach you, and opt-in by default so nothing changes until you flip it on.
If that sounds cautious, it should. Getting AI coaching text right is genuinely hard, and this is the pilot.
What actually changes
Save a planche or handstand analysis with the Coach AI narrative toggle on and the .saved screen now includes a Session Takeaway card — three short lines:
- A framing headline naming what you did.
- A specific observation weaving today's angle reading with your 30-day trend.
- One imperative for next session, cast in coach-specific vocabulary.
Nothing else. No multi-angle summary, no chart. One picked angle — the largest deficit in the best hold window — becomes one focused note. That constraint isn't a limitation, it's the finding: everything we tried beyond single-angle summaries hallucinated numbers on repeat runs.
Coach-specific vocabulary
Generic AI text was never the goal. "Focus on your hip angle next session" is what a chatbot says. What a coach says is "cue hips forward through the shoulders on next attempt."
movement_cues.json ships alongside the app with 22 authored coaching cues, indexed by movement × angle: planche variants (tuck, straddle, full) × 5 angles, and handstand variants (wall, freestanding) × 3 angles. When the model builds nextStep, the prompt injects the relevant cue for the picked movement + angle combination. The model translates the cue into a natural imperative sentence.
A recent test analysis produced "Drive hips forward and open shoulders through the next attempt." That's the exact vocabulary from the tuck-planche + hip-angle authored cue, wrapped in a fluent sentence. Not generic. Coach-real.
Movements not yet authored (front lever, back lever, elbow planche, muscle-up, etc.) fall back to the base prompt with no cue — generic imperative, still coherent. Adding cues per movement is a future content pass, not a code change.
30-day trend context
The observation field doesn't just report today's number. When you have ≥2 prior sessions on the same movement in the last 30 days, the prompt receives a pre-computed trend delta and direction from the same /coach/trends endpoint the Coach-tab Progress section uses. The model weaves it into the observation.
Example output from a recent Tuck Planche analysis: "Your 53° hip angle sits above 45° target; past thirty days, angle regressed by 5°." Both today's snapshot AND the month-over-month arc, in one sentence.
The trend delta is on the hallucination whitelist alongside the reading, target, delta, and hold seconds — so the model can quote it back safely. If it invents any other number, the check nukes the output and rule-based fallback takes over. Same safety net covers both features.
First-ever sessions and stable-trending angles gracefully degrade to the today-only observation. No fake trend claims when there's nothing meaningful to report.
Why this took so long
The v1.16 release post ended with "v1.17 will bring Coach text feedback to life if pilot testing goes well". Pilot testing did not go well the first time.
We shelved this project in July after an initial spike with iOS 26's Foundation Models (AFM 2) invented an integer that wasn't in the prompt — asked to observe a 175° target vs a 180° reading, the model narrated a "15° gap". A hallucinated arithmetic step that would have looked like a real coach's observation to anyone who wasn't checking the math. Not shippable.
Apple shipped AFM 3 Core Advanced at WWDC26 — a 20B-parameter sparse model with what Apple's calling Instruction-Following Pruning. We ran a fresh spike on August 3rd. Eight test cases across single-angle, multi-angle, direction-labelled, and lower-is-better prompts. Multi-angle still hallucinated. Direction-labelled ("higher = worse") still nudged toward "correct it" even when the reading was on the good side. But single-angle prompts with pre-computed deltas and celebration-framed lower-is-better prompts came back clean.
Then, on August 4th, the same case that had passed twice hallucinated on the third run. Same prompt, different output — the model is genuinely non-deterministic in a way a one-shot spike doesn't catch.
That's when we built the hallucination check.
The hallucination filter
Before any AI output reaches your screen, we run it through a whitelist check. Every integer in the response has to match an integer that was in the prompt — reading, target, delta, hold seconds. Anything else is by definition invented, and the model's output gets discarded silently. Your Session Takeaway either shows verified LLM copy or the rule-based fallback template. Never a made-up number.
That gate runs on every generation. When it catches a hallucination, we log it privately for our own metrics and fall back to the deterministic rule-based Coach cue you'd have seen anyway. The user experience is identical either way — same card shape, same three fields — with a small sparkles icon in the header when it's LLM output, hidden on fallback so devices without Apple Intelligence don't feel like they're getting a degraded product.
Constrained on purpose
Beyond the hallucination filter, three prompt-engineering guardrails are baked into this release and won't move without a lot of evidence:
Single angle at a time. Swift picks the angle with the largest deficit in your best hold window. The model gets one target, one reading, one pre-computed delta. Multi-angle summaries are deferred.
Never let the model do arithmetic. All deltas, directions ("above" vs "below"), and amounts are computed in Swift and passed to the prompt as named integers. The model interprets, it doesn't calculate.
Lower-is-better prompts are celebration-framed. For metrics where a lower reading is a better reading (shoulder protraction, for example), the prompt reframes the reading as an achievement below a ceiling. The word "target" and "delta" never appear — that terminology triggered the model's training-bias toward "correct it" even when the reading was on the good side.
Together those guardrails plus the hallucination gate give us copy we're willing to ship. Ten test analyses on-device before this release with zero hallucinations reaching the user.
Discoverable, not forced
The feature ships default off. New v1.17 users see no change to Coach unless they opt in.
There are two paths to opt in:
Profile toggle. A new "Coach AI narrative" section in Profile with a plain toggle. Flip it on, next save gets narrative. Flip it off, back to numbers.
Inline hint on the save screen. If the toggle is off, your first few saved analyses include a small dismissible card with a "Try it" button. Tap it once and the flag flips on, the hint disappears, and the narrative generates for the analysis you just saved. Tap "Not now" or the × and the hint is gone permanently. It never nags. Never blocks. And it's user-scoped, so a new sign-in gets a fresh hint.
That's the whole discoverability strategy. Release notes point you to it, the hint mentions it once in-app, and after that you have to want it. Data will tell us whether that's too subtle in a week or two.
Latency and eligibility
The Foundation Models framework requires iOS 26 and an Apple Intelligence-eligible device (iPhone 15 Pro and up, plus iOS 26-eligible iPads and Macs). Users on older devices see the same card design filled from the rule-based fallback templates — no AI, no visual signal that AI is happening elsewhere.
On-device generation takes 1.5-3.5 seconds after warmup, closer to 6-7 seconds on the very first call of the app lifecycle. Your save transitions immediately; the narrative slots in a moment later. If generation errors or times out, the card silently uses the fallback.
Zero data leaves your phone. Everything runs on the neural engine.
What we're watching
Two questions this pilot is meant to answer:
Do users who opt in retain better? If AI coaching text meaningfully increases the "did another analysis this week" rate, that's signal to invest further. If it's flat, this feature stays a pilot and we spend engineering time elsewhere.
How often does the hallucination filter fire? We're monitoring the ratio of LLM-source vs fallback-source generations. If fallbacks stay under 15% of generations, the model is behaving. Above 30% would mean either the prompt-engineering guardrails aren't holding or the model is regressing across iOS betas — and we'd shelve the whole path until Apple ships a stable AFM 4.
What else
- The whole
HallucinationDetectorsits in production code, not a debug harness. Every generation goes through it. The playground harness we used to spike this is DEBUG-only and doesn't ship to the App Store binary. - User-scoped UserDefaults keys now include the AI narrative hint dismissal — sign out and back in with a fresh account gets a fresh hint, no leaking of prior-user state.
- 3 new unit tests covering the prompt library, fallback synthesis, and the hallucination detector itself. Runtime behavior remains verified device-side.
What's next
If the pilot metrics land in the acceptable window, v1.18 or v1.19 will consider defaulting the feature on for Apple Intelligence-eligible devices — with the same fallback + hallucination gate untouched. If they don't land well, the feature stays opt-in indefinitely, or the whole path gets shelved until AFM 4.
Meanwhile the Coach ruleset tuning arc continues. Front lever, back lever, and elbow planche variants have facit clips waiting to be captured; every one produces sharper thresholds and better rule-based fallback copy — which the AI narrative reuses on ineligible devices.
Bug reports and feature ideas: support@zenmotion.app.
Train well.