From f45ba35e25779fe4d071769d6df5af0a91bd16f5 Mon Sep 17 00:00:00 2001 From: mathias Date: Wed, 3 Jun 2026 20:59:14 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20VISION=20Stage=200=20=E2=80=94=20keep?= =?UTF-8?q?=20"unprompted"=20as=20ideal,=20note=20measurement=20gap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reframes "unprompted" from an enforced criterion to a named measurement limitation: organic-vs-prompted returns aren't distinguishable from any data Tapir holds, so in practice all returns are counted and the result read with that caveat (a nudged return is a weaker signal). Adds a "how it's measured" note pointing at summary_actions (acts) + a new append-only login-events table (read-returns), which accrue from deploy onward. Honest about the gap rather than silently dropping the word. --- VISION.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/VISION.md b/VISION.md index 56c9170..0ca53f9 100644 --- a/VISION.md +++ b/VISION.md @@ -59,8 +59,11 @@ to the next stage's ambition until the current stage's test passes. ### Stage 0 — Useful to me or a friend (the gate) > **Headline test:** Over a 3–4 week window, *either* the maintainer *or* at least one -> onboarded friend returns to Tapir **unprompted** and reads/acts on summaries in **≥2 -> separate weeks**. The test is *return usage* (behavioural), not stated approval. +> onboarded friend returns to Tapir and reads/acts on summaries in **≥2 separate weeks**. +> The test is *return usage* (behavioural), not stated approval. The ideal signal is an +> **unprompted** return (organic, not because the maintainer nudged them) — but see the +> measurement note below: we currently cannot distinguish prompted from organic returns, so +> in practice we count all returns and read the result with that caveat. - Captions-first summarization works end-to-end for real subscriptions (the maintainer's and onboarded friends'). @@ -69,12 +72,24 @@ to the next stage's ambition until the current stage's test passes. most of the time. - **Why behavioural, not feedback.** Friend *feedback* is gathered and genuinely valuable — but it is **not** the gate. Asked-for feedback from friendly users is the least reliable - signal in product development (politeness bias); whether they *come back on their own* is - the thing we actually care about. So the gate measures returns, not nice words. + signal in product development (politeness bias); whether they *come back* is the thing we + actually care about. So the gate measures returns, not nice words. +- **Measurement note — "unprompted" is an ideal we can't yet measure.** Whether a return was + organic or prompted by a nudge is not captured by any data Tapir holds (it's context only + the maintainer has). Rather than waive the standard, we name the gap: *unprompted* return + is the signal we genuinely want; *returns* (prompted or not) is what the data can show. A + return that needed a nudge is a weaker signal than one that didn't, and the result is read + with that in mind. If distinguishing them ever matters enough, the maintainer tracks nudges + manually or a future build records prompt events — neither is in scope now. - **Why "me OR a friend".** This replaces the original "useful to *me*, specifically" gate (2026-06-03 decision, recorded in DECISIONS.md ADR-016). Getting signal from friendly users is valuable enough to count — but the bar stays behavioural so it can't be cleared by a polite reaction. (Ties to the 2026-07-01 check-in.) +- **How it's measured.** Return usage is read from two sources: `summary_actions` (timestamped + watch/skip/save per user) answers "acted in ≥2 distinct weeks"; an append-only login-events + table (see infra/Tapir build) answers "returned/read in ≥2 distinct weeks" even without an + action click — the honest signal for a *reading* product. Login events accrue only from their + deploy date onward, so the gate window's data begins then. - **This is the gate.** Hardening (Stage 1) and any SaaS ambition stay deferred until this behavioural signal exists. Note: multi-user machinery was deliberately built *ahead* of this gate (ADR-012) with isolation enforced — that was an explicit, recorded call, not a