SpeakTrue

Next Product Direction: 90-Day Roadmap

Status

Proposed execution roadmap. This document sequences three implementation-ready plans:

1. Conversation Workspace
2. Unified Speech Library
3. Quick Speak Accessibility Mode

The roadmap is intentionally outcome-based. Week ranges are sequencing guides, not release promises. Each feature must pass its own rollout gate before the next dependency is treated as available.

Product Direction

Move SpeakTrue from a collection of speech tools toward a dependable communication workspace:

• capture a spoken turn, hear it revoiced, and keep the surrounding context;
• find and reuse prior speech without remembering its folder;
• speak a prepared or newly typed phrase quickly, including when cloud generation is unavailable.

The existing TTS, STT, STS, Soundboard, artifact, auth, and entitlement paths remain the foundation. The roadmap adds workflow continuity around them rather than replacing their contracts.

Current Baseline

• Turn-Based STS (live_interpreter) is the account-synced default across iOS, Android, and web.
• A completed STS turn currently resolves to one visible transcript and one latest generated artifact, not a durable multi-turn timeline.
• sts-realtime-finalize is the artifact handoff and preserves artifact_id, artifact_path, audio_path, download_path, transcribed_text, and clip_metadata.
• soundboard_clips is the canonical reusable audio record. It supports categories, transcript text, generation metadata, ordering, and offline availability, but it has no first-class favorites, tags, or cross-category search.
• iOS and Android have no app-shortcut or system-speech Quick Speak surface.
• Existing usage events are appropriate for provider accounting, but product telemetry needs a separate, content-free event vocabulary before roadmap metrics are trusted.

Non-Negotiable Boundaries

• Preserve existing batch, realtime, and Turn-Based STS compatibility paths.
• Do not describe revoicing as translation. Current STS sends committed transcript text to TTS; a translation provider and source-to-target text contract are separate future work.
• Keep provider keys and privileged writes behind Supabase edge/server boundaries.
• Never store signed artifact URLs. Persist stable IDs and storage paths, then resolve short-lived URLs at read time.
• Never emit transcript or Quick Speak phrase text into logs, analytics metadata, shortcut URLs, or crash breadcrumbs.
• Basic local Quick Speak and platform speech fallback must not require a paid plan.
• Android-affecting slices must pass bash scripts/verify_android_ci_local.sh before commit or push.
• Each schema rollout must remain backward compatible until all three clients and legacy web have migrated.

90-Day Outcomes

Outcome	User-visible proof	Release measure
Conversation continuity	A user completes several Turn-Based STS turns, replays any turn, leaves, and resumes the conversation	At least 95% of accepted turns attach to a conversation; attach failures are recoverable and idempotent
Speech retrieval	A user searches all clips, filters favorites or sources, and plays a result without opening its folder first	Median signed-in retrieve-to-play time under 3 seconds on a warm network path
Fast accessible speech	A user opens Quick Speak, enters or selects a phrase, and hears it with one primary action; a platform voice remains available offline	Local fallback success above 99% in device tests; no phrase content in telemetry
Cross-platform contract stability	Web, iOS, and Android decode the same new fields while old clients continue to function	Contract tests and per-surface gates pass with old fields remaining valid

Metrics are proposed targets. Baseline measurement must precede any claim that a target has been met.

Sequence

Days 1-15: Contract and measurement foundation

• Correct STS product language so revoicing and translation are not conflated.
• Define content-free workflow events and latency points.
• Add ephemeral multi-turn timelines to the existing Turn-Based STS experience, beginning with web and then native parity.
• Define the Unified Library read envelope without changing current Soundboard routes.
• Prototype native Quick Speak with local-only phrase state and existing speech services.

Exit gate: each concept is demoable without a new durable schema, and user-flow observations confirm that the chosen interaction is worth persisting.

Days 16-35: Durable conversation and library read path

• Add conversation and turn persistence with RLS and idempotent artifact attachment.
• Add the paginated Unified Library query path over soundboard_clips.
• Ship web conversation resume and cross-category recent/search.
• Add favorite state and mutation contracts.
• Establish iOS and Android decoding models behind disabled or internal-only UI flags.

Exit gate: an old client still completes STS and loads Soundboard; a new web client can resume a conversation and search/favorite clips.

Days 36-60: Native parity and Quick Speak reliability

• Ship conversation resume and Unified Library search/favorites on iOS and Android.
• Add system-speech fallback to Quick Speak on both native platforms.
• Add synced pinned phrases through a dedicated phrase contract.
• Resolve signed URLs only when a library result is played or shared.
• Run accessibility reviews for Dynamic Type/font scaling, screen readers, focus order, contrast, switch access, and reduced motion.

Exit gate: all native slices pass focused tests; Android passes its complete local gate; manual device tests demonstrate network failure recovery.

Days 61-75: Integration and shortcuts

• Allow a completed conversation turn to be saved to Soundboard without losing source metadata.
• Allow Soundboard favorites and pinned phrases to feed Quick Speak.
• Add iOS App Shortcut and Android app-shortcut entry points using opaque phrase IDs.
• Add explicit recovery for orphaned finalized artifacts and failed conversation attachment.
• Add content-free dashboards for latency, failure class, fallback use, and reuse.

Exit gate: the three plans form one flow—complete a turn, save or pin it, find it later, and speak it quickly.

Days 76-90: Hardening and staged release

• Exercise migrations against a production-like snapshot and test rollback paths.
• Run cross-platform parity, accessibility, auth-expiry, offline, and poor-network scenarios.
• Release behind independent server-controlled flags in this order: internal accounts, allowlisted beta, percentage rollout, default-on.
• Review metrics and user feedback before enabling each subsequent flag.
• Publish operator notes and update docs/index.md when each plan changes from proposed to active or implemented.

Exit gate: rollback has been rehearsed, support diagnostics do not contain content, and no compatibility client is forced onto a new contract.

Dependency Map

flowchart LR
    C0["STS semantics and ephemeral timeline"] --> C1["Persistent conversations"]
    C1 --> I1["Save a turn with provenance"]
    L0["Unified Library query"] --> L1["Favorites and tags"]
    L1 --> I1
    Q0["Native local Quick Speak"] --> Q1["System speech fallback"]
    Q1 --> Q2["Synced pinned phrases"]
    L1 --> Q2
    Q2 --> Q3["App shortcuts"]
    I1 --> R["Integrated staged release"]
    Q3 --> R

Conversation persistence and the library read path can proceed in parallel after their contracts are fixed. Shortcut work depends on stable phrase identity. Quick Speak’s local MVP does not depend on the Unified Library.

Release Flags

Use separate flags so one feature can roll back without disabling another:

• conversation_workspace_enabled
• speech_library_enabled
• quick_speak_enabled
• quick_speak_system_fallback_enabled
• quick_speak_shortcuts_enabled

Flags belong in server-controlled settings or the existing app configuration boundary. Do not use compile-time-only flags for staged production rollout.

Measurement Contract

Record only operational metadata:

• random event ID;
• authenticated user ID at the protected server boundary;
• platform and app version;
• workflow mode;
• result class and stable error code;
• elapsed milliseconds;
• fallback used;
• counts such as turn count or result count.

Do not record transcript text, phrase text, clip filenames, storage paths, signed URLs, voice samples, or provider credentials. Product events must be distinguishable from billable provider usage_events so experimentation does not alter quota accounting.

Proposed event names:

• conversation_started, conversation_turn_finalized, conversation_resumed;
• library_query_completed, library_item_played, library_favorite_changed;
• quick_speak_opened, quick_speak_playback_started, quick_speak_fallback_used.

Verification Strategy

Every slice runs the narrowest relevant checks first, then the full surface gate when required:

# Backend contracts and migrations
npx -y deno@latest test backend/supabase/functions/<touched-function>/*_test.ts
bash scripts/coverage_backend_contracts.sh
bash scripts/regression_migration_paths.sh

# Web
web/python-web-app/venv/bin/pytest <focused-test-files>
node --check web/python-web-app/static/js/<touched-file>.js
node web/python-web-app/tests/js/<focused-runtime-check>.mjs

# iOS
xcodebuild test -project ios/SpeakTrue.xcodeproj -scheme SpeakTrue \
  -destination 'platform=iOS Simulator,name=iPhone 17' \
  -only-testing:SpeakTrueTests/<FocusedTestClass>

# Android, mandatory for any Android-facing slice before commit/push
bash scripts/verify_android_ci_local.sh

# Every slice
git diff --check
git status --short

Migration slices also require a rollback rehearsal and a live Supabase smoke against an allowlisted test account before broad rollout.

Decisions Required Before Day 16

1. Product naming: keep Live Interpreter as a historical mode label or rename it to Turn-Based Revoice until true translation exists.
2. Retention: default durable conversation retention period and user-facing deletion controls.
3. Sync: whether pinned Quick Speak phrases are opt-in or sync by default for authenticated users.
4. Telemetry: where content-free product events live and how long they are retained.
5. Web scope: Quick Speak is native-first in this roadmap; decide whether a web surface belongs in the same release or a later plan.

Definition of Roadmap Completion

• Each linked plan has completed its MVP slices and its staged rollout gate.
• A user can complete, resume, retrieve, reuse, and quickly speak content across the supported surfaces.
• Old app versions continue to complete core TTS, STT, STS, and Soundboard flows.
• Privacy, accessibility, offline, auth-expiry, and rollback evidence is attached to the release record.
• docs/index.md, operator docs, schema snapshots, and Obsidian project notes match deployed behavior.