README leaks code-level internals into user-facing sections — keep the user layer separate from the implementation layer

[bepcyc]

Problem

The README mixes the implementation layer into user-facing sections. A non-technical cyclist gets the engineering retelling — issue numbers, spec IDs, internal component names, CI/release plumbing — instead of "what do I get." It reads as built-by-a-megageek-for-megageeks, which repels the actual target reader. The ## For developers section is the right home for tech detail; the leak is everywhere else.

All evidence below is quoted verbatim from the current README on main.

The leaks (quoted)

1. ## Roadmap — the worst offender. It is a dev changelog wearing a user roadmap's clothes. A user does not care about issue numbers, spec IDs, or internal mechanisms:

• > #98 — VOICE-R2: turn the presentation strip into an allow-list so no internal metric code can ever leak into athlete-facing prose. — spec ID, "presentation strip", "allow-list".
• > #103 — Scope the slow CI tiers to the change: a docs/text-only PR shouldn't pay the database, e2e, and image-build tax... — pure CI internals; zero user relevance.
• > #39 — Wire durability ... with \work_above_cp_j` persisted on ingest so the number can be retrieved and cited.—work_above_cp_j`, "persisted on ingest".
• > #87 — Two-layer coach answer: a verifiable evidence layer the grounder reads ... split fail-closed... — "grounder", "fail-closed", "two-layer".
• > #97 — Make the checkpoint \interrupt_id` stable across pause/resume (a known LangGraph re-run quirk; the fix may be a deterministic id or a documented spec carve-out).—interrupt_id`, "LangGraph re-run quirk", "spec carve-out".
• > #93 — Remove false-confidence tests (including GDPR-erasure tests that never exercise the production erase path)... — test-suite internals.

2. Quick start — honest, but written in engine terms.

• > ...its connect path is intentionally inert here — it returns \422` until a credential probe is configured — so it will not pull data in the stock OSS container.` — "credential probe", "422", "stock OSS container" at a first-run user.
• > # Prefer not to build? A released image exists, but note it is the pinned v0.0.1 snapshot, is linux/amd64 only, and may trail these docs: — "pinned snapshot", "may trail these docs" is release-engineering, not user copy.

3. ## How it works — mostly fine, one config-jargon line:

• > Storage is a single connection string: SQLite by default, or PostgreSQL or MariaDB by changing that one setting... — "connection string" / "that one setting".

Proposed changes

Guiding rule: user-facing sections say what the user gets, in plain words. Issue numbers, spec IDs (VOICE-R2), internal component names (grounder, work_above_cp_j, interrupt_id, "credential probe"), and CI/release plumbing live in the GitHub issues/milestones, CONTRIBUTING, the ## For developers section, and the source — never in the user README.

1. Rewrite ## Roadmap as user outcomes. Keep the nice codename framing (Banister / Coggan / Seiler + one line on what the release is about). Replace every #NN — <engineering> bullet with at most one plain sentence on what the user will be able to do (e.g. "v0.0.2 — more of the metrics you know, and the coach can cite them"). Drop issue numbers and spec IDs entirely; they already live on the GitHub milestones, which is where a contributor looks.
2. Plain-language the intervals.icu note. e.g. "Automatic sync from services like intervals.icu isn't available in this build yet — for now, bring your data in by uploading files (above)." No 422, no "credential probe", no "stock OSS container".
3. Plain-language the released-image note. e.g. "Building from source is recommended and runs on any machine. (A prebuilt x86-only image also exists.)" Drop "pinned snapshot / may trail these docs."
4. Trim the storage line in How it works to "Runs on SQLite out of the box; point it at PostgreSQL or MariaDB when you outgrow it."
5. Leave ## For developers as-is — that is the correct place for the stack, the test tiers, and the OpenAPI surface.

Acceptance

A reader who is a cyclist, not an engineer, can read the whole README and never meet an issue number, a spec ID, an internal component name, or a CI/release detail outside ## For developers. Implementation detail is findable (issues, dev docs, source) but not pushed at the user.

[bepcyc]

Review

Strong agree on the thesis, and the evidence holds — I checked every quote against the current main README and they're all verbatim and in the sections you name. So this is a real problem, well diagnosed. What I want to add isn't disagreement; it's (1) a sharper definition of what "user-friendly language" actually is, so the rewrite doesn't over-correct, (2) a few leaks this misses, and (3) a way to stop it from coming back.

1. The leak is point-of-view, not just vocabulary

De-jargoning is necessary but not sufficient. Take #95 — Surface the gathered activity id into the compose fact sheet. Strip every identifier and you get "improve internal data flow" — still meaningless to a user, because it's still author-POV ("what I will build") where the user asks exactly one question: "what will I be able to do that I can't today?" The roadmap answers the maintainer's question in a user's section.

So the rule I'd write on the wall: every user-facing sentence is about a capability the reader gains, in words the reader already owns. Note that "in words the reader already owns" is not the same as "no technical words" — TSS, fitness/fatigue/form, Critical Power are technical and they're fine, because your reader already owns them. grounder, presentation strip, work_above_cp_j are not. The test isn't "is this word technical," it's "does the reader already have this word." Your top sections ("Your power meter never lies") pass this effortlessly; the roadmap just stopped obeying the document's own voice.

2. Cut vs. translate — the distinction that matters most for an honesty-first project

This is the part I'd be most careful about, because a careless pass will do real damage here. Some of what reads as a "leak" is actually honesty to the user wearing engineer's clothes, and the fix is to translate it, not delete it:

• intervals.icu. The load-bearing fact is "automatic sync doesn't work in this build — upload files instead." That is the single most important thing a new user must know before they sit there wondering why nothing imports. It is not plumbing. Your proposed rewrite (style: apply ruff format repo-wide + decompose modules past size ceilings #2) keeps the fact and drops the 422 / "credential probe" — exactly right. The principle worth stating out loud, because it is your brand: for a project whose whole pitch is "never makes the numbers up," user-friendly never means hiding an inconvenient truth — it means telling it in the user's vocabulary. Sanitize the caveat into marketing fog and you've betrayed the thing that makes wattwise wattwise.
• The released image. linux/amd64 only is a genuine user constraint — an Apple-Silicon or Raspberry-Pi owner needs to know the prebuilt image won't run for them — so keep it, as "x86/Intel only." "Pinned snapshot / may trail these docs" is maintainer anxiety; cut it. Your chore(deps): adopt httpx2 for the starlette test client #3 makes the right cut; I'm only naming why, so the rewriter trims surgically instead of dropping "x86-only" along with the rest.

So the operational version of §1 is a two-part test, per sentence:

1. Does the reader need it to decide or act? No → cut.
2. Is it in words the reader already owns? Passes (1) but fails this → translate, don't cut.

The roadmap is almost all pure (1)-failures (cut). The Quick-start caveats are mostly (2)-failures (translate). Treating them the same is the one way this change goes wrong.

3. A few leaks the issue doesn't list (extending the scope)

• Same intervals.icu paragraph: GET /v1/connections/available, "the engine also ships … connector," "api-key connector" — same author register, same cut.
• Quick-start reassurance (the paragraph after docker run): "no extra migration step," "runs as an unprivileged user," "a bad configuration stops startup instead of running on quietly." Written for an ops reviewer. Translation: "It sets itself up on first run, and refuses to start if it's misconfigured rather than fail silently." (Note this is a translate, not a cut — the reassurance is worth keeping.)
• "How it works" flow line ends in → API. Fine inside ## For developers; a dead end as the last box a user reads.

4. The honest bigger picture (a scope call for you, not a demand)

The reason the README "reads built-by-megageeks-for-megageeks" is only partly vocabulary. The deeper cause is that the only path in is a terminal and curl — minting a token, Bearer, -F file=@…, polling /readyz. You can make every word friendly and a non-technical cyclist still cannot finish Quick start, because the medium is an API walkthrough. I don't think that belongs in this issue — but it's worth saying plainly that the language fix has a ceiling set by the curl-only UX, and the "real" user-friendliness milestone is a non-curl path. Probably a sibling issue. Flagging it so "make the README user-friendly" doesn't quietly get read as "the product is now usable by non-engineers."

5. Two things to protect in the rewrite

• Keep the domain richness. Your reader is a domain enthusiast — "athletes who read the papers," per your own footer — not a layperson. The Banister / Coggan / Seiler lineage paragraphs are good geeky: exactly the detail this reader delights in. The cut is implementation (issue numbers, grounder, interrupt_id), not sports science (Banister, TRIMP, the why-this-name story). "User-friendly" here means speak to the informed enthusiast, not flatten to the lowest common denominator. You already say "keep the codename framing" — I'd make that load-bearing, because an over-eager pass will strip those paragraphs as "too much," and that's the wrong cut.
• Keep one pointer to the work. Replacing #NN — bullets with outcomes is right, but a roadmap that links nowhere stops being a roadmap and becomes a brochure. A single line — "Track the work on the milestones" — preserves the "findable, not pushed" half of your own acceptance criterion.

6. Stop it regressing (the strongest extension)

This README is under active churn — #111, #112, #113 just reworked onboarding back-to-back — and nothing stops the next PR from re-leaking. The thing is, you've already solved this exact problem one layer in: #98 turned the coach's presentation strip into an allow-list "so no internal metric code can ever leak into athlete-facing prose." The README is the same problem one layer out — internal vocabulary leaking into human-facing prose — so apply the pattern you already endorsed:

• a short voice contract in CONTRIBUTING.md (the two tests in §2), and
• optionally a cheap lint over everything outside ## For developers that fails on #\d+, spec IDs (VOICE-…), backticked snake_case, and bare 422 / DSN / amd64.

That turns your acceptance criterion from eyeballed into enforced, and it's philosophically consistent with how you already guard the coach's prose.

Net

Ship the rewrite as proposed — but through the cut-vs-translate lens (§2), so the honest caveats survive in plain words rather than getting deleted as "plumbing." Fold in the missed leaks (§3), protect the domain richness and a milestone link (§5), and consider the §6 guard so this is the last time anyone files this issue. The one item I'd genuinely escalate to you is §4 — whether "user-friendly README" should also spawn a "user-friendly path in" issue, since that's the actual ceiling on how friendly the words can ever make this feel.

---

Generated by Claude Code