Skip to content

SailEver specs

The specs describe what every SailEver product does today, down to each value on each screen. They are the single source of truth for behaviour. Code implements the spec; if the two differ, one of them is wrong and gets fixed in the same change.

Terms follow glossary.md. It is always track, never leg.

Layout

Folder Product Implementations
watchapp/ WatchApp: records tracks on the wrist Garmin (apps/garmin-watchapp), Wear OS (apps/android), Apple Watch (planned)
datafield/ DataField: sailing values inside Garmin's own activities Garmin (apps/garmin-datafield)
server/ Website, logbook and API Rails (apps/server)
mobile/ Phone apps (planned) iOS, Android (click dummies in ../companion_app/)
shared/ Contracts and rules used by more than one product SLTB track sync, device API, vessel states, calculations

open-questions.md lists product decisions that are still open (a spec describes today's code; the question says what might change). watchapp/parity.md lists where the watch platforms differ without a platform reason.

Everything else in docs/:

Folder Holds Rule
../adr/ Decisions and their reasons Append-only. A later ADR supersedes an earlier one.
../plans/ Work that is not built yet When it ships, the behaviour moves into a spec and the plan is deleted.
../marketing/ Film scripts, pricing Not a spec.

Repo-local AGENTS.md files hold how to build, test and find code, never behaviour.

Rules

  1. One place per fact. A fact lives in exactly one spec file. Other files link to it, they don't repeat it.
  2. General first, then platform. Each section describes the behaviour shared by all platforms first. Platform differences follow under ### Garmin, ### Wear OS, ### Apple Watch (or ### iOS, ### Android) in that order, and only state what differs.
  3. Platforms stay in sync. A change that isn't platform-specific is made on every implemented platform in the same piece of work. If that's not possible, the gap goes into the product's parity.md with the reason.
  4. No change requests, no *_v2.md. Edit the spec in place, in the same commit as the code. Git history is the change log.
  5. Bugs and open decisions are visible. Where code is wrong, the spec still describes what the code does and lists the bug under Known deviations. A decision that is still open goes into open-questions.md and is deleted there once decided.
  6. The spec is updated with the code. Before handing back work that changes behaviour, the agent updates the spec (/spec-update). mise doccheck checks the obvious things (banned terms, broken links, code paths that no longer exist).
  7. Stated as fact, present tense. "The SOG shows one decimal", not "should show". Planned things are marked ⏳.

  8. Privacy is not optional. Every product follows shared/privacy.md: watch apps send nothing before the user consents on the watch, web consent is stored, and every user can delete the account with all its data. A spec change that touches data collection, storage or an outside service checks it against that file.

  9. The specs are the detail, the architecture is the map. ../architecture/ (arc42) says how the system is built and why, and links here. It never repeats a spec; a change to a building block, runtime flow, quality goal or decision updates it in the same change.

Spec file template

# <Screen or feature>

| | Garmin | Wear OS | Apple Watch |
|---|---|---|---|
| Status | ✅ | ✅ | ⏳ |
| Code | `source/views/DashboardView.mc` | `wear/…/views/DashboardView.kt` | — |

Verified against code: 2026-10-11

## Purpose
One paragraph: what the user gets from it.

## Layout / behaviour
General description, then one table per area of the screen:

| Element | Position | Font / size | Colour | Content & format | Constraints |
|---|---|---|---|---|---|

Positions are fractions of screen width / height (x 0.50 = centre), so they hold on every screen size.

### Garmin
### Wear OS
### Apple Watch

## States and edge cases
No fix, no barometer, values out of range, very small screens.

## Known deviations
Where an implementation differs from this spec and it's a bug, not a decision. Link the issue if there is one.

Status markers: ✅ implemented · 🟡 partly / differs (see Known deviations or parity.md) · ⏳ planned · — not applicable.