Flat Terrain Race Pace and Estimated GAP
Date: 2026-10-26
Status: Approved by the user on 2026-10-26
Intent
An athlete entering a manual race pace should understand what to enter, without seeing that input repeated as a supposedly calculated GAP. Target Time should separately explain the grade-adjusted pace of its schedule and the flat-terrain input needed to reproduce its finish time in manual mode.
Approaches
- Show one required flat-equivalent pace. This gives a convenient manual input, but includes assumptions beyond gradient and cannot accurately serve as GAP.
- Separate Estimated GAP from Required Flat Terrain Race Pace. This adds one explanation but gives each number a clear meaning and preserves the round trip.
The user chose approach 2, with contextual guidance rather than a fixed reminder.
Manual pace
- Rename the manual mode to Flat Terrain Pace and its input to Flat Terrain Race Pace.
- Show a short explanation beside the input, rather than only in a tooltip: "The pace you expect to sustain on flat, runnable ground at your planned race effort. RaceCraft adjusts this for climbs, descents, terrain, fatigue and wind."
- Remove the manual Estimated GAP summary card and the repeated
base-pace-gap-containerresult. Rename its guidance heading to Flat Terrain Pace Guidance, retaining the climbing-rate guidance. - Keep the existing manual forward model and configurable controls.
Two Target Time measures
Estimated GAP appears in the summary card. It describes the planned moving paces after removing the effect of gradient alone. Surface difficulty is a separate effect and is not removed by a metric labelled grade-adjusted pace.
Calculate each leg's flat-equivalent moving time using its unrounded planned moving time divided by its existing split-ascent/descent Minetti grade factor. Sum those adjusted times and divide by total distance. Exclude checkpoint stops. Reuse the existing descent-credit model and grade bounds; do not average signed route gradients, since climbs and descents must not cancel. This is RaceCraft's estimate, without claiming numerical equivalence with Strava. Runnable climbs adjust to a faster equivalent pace and runnable descents to a slower one; extreme descents follow the model rather than an unconditional speedup rule.
Required Flat Terrain Race Pace appears in Target Time's existing collapsible guidance. It is the manual input whose forward prediction reproduces the target moving time under the fixed defaults below. Solve against the existing forward model, including its pace caps, then add the same checkpoint stops. This number is distinct from Estimated GAP and is the number to copy into manual mode.
Target Time's segment allocation and fixed total continue to use the existing Target Time engine. The new measures describe that schedule; they do not replace its segment allocation with the forward model.
Explicit defaults
Target Time's required flat-terrain pace always uses this baseline, independent of previous manual entries, hidden controls, saved athlete preferences or profile values:
| Setting | Default |
|---|---|
| Terrain adjustment | On |
| Technical skill | Strong (0.5) |
| Fatigue | On |
| Fitness | Recreational |
| Wind adjustment | On |
| Wind exposure | Mixed |
Terrain adjustment also defaults to on for new manual plans. Existing route, checkpoint, stop-time and selected segment terrain data remain explicit plan inputs. Wind uses the plan's race date, start time and available forecast, with the existing still-air fallback when unavailable. Previous manual pace must not affect Target Time's required pace through forecast scheduling or other inputs.
Builder's proposed scope: fixed defaults govern Target Time's derived pace and new-plan defaults. Switching modes does not silently reset an athlete's explicit manual edits or rewrite saved plans; those values cannot influence the Target Time baseline and any differences are explained when returning to manual mode.
Contextual guidance
Place small, muted helper text in the Pacing input panel. In Target Time it explains the fixed assumptions behind the required flat-terrain pace. After switching to manual mode, compare visible settings with that baseline and name only the changes needed to reproduce the target, for example: "To match your target, enable terrain adjustment and set fitness to Recreational." When settings match, show a brief confirmation and the rounding qualification.
The comparison also accounts for technical skill, fatigue, wind/exposure and changed checkpoint stops or route/terrain inputs. Ignore dependent values when their parent adjustment is off. A changed route requires recalculating the target reference; do not offer a stale pace as equivalent. A newer forecast can change the forward result and must not be described as a settings mismatch.
Keep only the active target calculation as the comparison reference; do not add a history of remembered athlete settings. Clear or replace the reference on a new plan or recalculated target. Do not silently restore or change controls.
Round trip, compatibility and limits
- The contract concerns finish totals; identical segment paces are not required.
- Test Target Time -> displayed required pace -> manual calculation using real UTA50/UTA100 routes, matching baseline settings, stops and stable conditions. Allow the error attributable to whole-second pace rounding and response precision, rather than inventing one universal time tolerance for all courses.
- Report solver-bound or unavailable results without claiming equivalence.
- Keep request/save identifiers such as
base_paceandz2_pacecompatible. Preserve legacy response fields and add explicit fields for the two new meanings. Never present an older saved flat-pace anchor as grade-only GAP; recalculate missing measures or leave them unavailable. - Cover grade-only GAP on flat, climbing, descending and rolling real-route legs, independence from hidden manual settings, contextual guidance changes, unit conversion, save/load compatibility, localisation and accessibility.
- Use existing components and theme tokens. Extract all copy to
en-AU.json; preserve disclosure behaviour and update model documentation with the changes.
Non-goals and remaining builder choices
No new segment-table GAP column, physiological model, pace estimator, framework, deployment or release is included. The builder chooses additive response field names, helper functions and precise test tolerances during planning. The earlier 2026-06-01 GAP-unification proposal does not authorise a broader model rewrite.