Implementation Plan: Proactive Context Prompts MVP
+Implemented on branch codex/185-proactive-context-prompts
+Issue: #185. Revised 2026-06-20 after plan review. Scope: one non-safety detector, stateful Telegram prompt lifecycle, privacy-safe detector-specific annotations, and illness-safety non-regression.
+ +Task Summary
+Build a narrow first slice of interactive proactivity: when one selected non-safety detector notices a strong unusual pattern, reserve and send one Telegram prompt asking for broad context, then store the user's closed-enum answer. The annotation applies to the specific detector only and is used in future reports; it does not alter readiness scoring or illness-safety logic.
+The plan intentionally reduces the earlier broad design. First slice means one detector, one prompt lifecycle, one storage model, one callback path, one tenant rollout, and measurable stop/go criteria.
+The implementation separates two roles: low_sleep_v2 is a candidate detector, while a separate prompt-usefulness gate decides whether asking the user is worth it.
Review-Driven Changes
+-
+
- Replace
category NOT NULLannotation rows with an explicit prompt/interaction state machine wherecategoryis nullable until answered.
+ - Use
signal_dateandprompt_local_dateas separateDATEfields. Do not use ambiguousdate TEXT.
+ - Deduplicate signals by
signal_date + detected_reason, not by source.
+ - Use an opaque
prompt_idin Telegram callbacks. Do not put date, detector reason, or category as the identity in callback payload.
+ - Expire callbacks by
expires_at, not by "callback date equals today". A morning prompt commonly explains yesterday's signal.
+ - Start with one non-safety detector. Defer respiratory/oxygen and high-autonomic-load prompts until the UX proves itself. +
- Rename
ignore_signaltoskip_context/unknown_contextso users do not think safety warnings are disabled.
+ - Stored context applies to one detector only, not the whole day. +
- Answers apply to future reports. First slice does not edit an already-sent report. +
Inspected Current Architecture
+-
+
internal/notify/proactive.gosupports one-way proactive notifications with cadence and error isolation. It does not model a prompt lifecycle, reservation, expiry, or answered state.
+ internal/storage/subjective_checkin.gohas a robust check-in state machine and stale callback protection, but its "date must equal today" rule is specific to morning check-ins and is not valid for context prompts about prior-day signals.
+ internal/notify/checkin_callback.govalidates chat/tenant routing and rejects stale check-in callbacks before storage mutation. The context flow should reuse tenant lookup style but not reuse date semantics.
+ internal/storage/briefing.gocomputes illness suspicion and applies safety caps before report output. Context annotations must sit beside this, not inside it.
+ internal/health/illness.goalready has non-diagnostic wording tests and safety cap tests. These become regression anchors for this feature.
+ internal/notify/report.goandinternal/notify/report_rich.gocan show future detector-specific caveats after a prompt is answered, gated behind a separate display setting.
+
Illness-Safety Boundary
+This feature must complement illness detection, not compete with it.
+-
+
IllnessSuspicionremains the safety layer. It can cap readiness confidence and EnergyBank recommendation when objective evidence is moderate/high.
+ - Context prompts are an explanation layer. They ask for broad context and mark one detector result as explained or skipped. +
- Context answers must not lower illness confidence, remove illness signals, or undo illness safety caps. +
illness_contextis not part of MVP category choices. When added later, it must not feedComputeIllnessSuspicionas subjective illness evidence without a separate validation plan.
+ - Safety-sensitive detectors such as respiratory/oxygen shifts are explicitly out of the first slice. +
Privacy Boundary
+-
+
- No free text in Telegram, storage, logs, issue comments, docs, Gemini prompts, or report caveats. +
- No specific medical procedures, diagnoses, clinic names, physician names, locations, personal names, or real person/date examples in public artifacts. +
- Allowed stored categories for MVP:
poor_sleep_context,stress_context,travel_context,unknown_context,skip_context.
+ - Allowed metadata: detector key/version, numeric value/baseline/z-score/percentile, prompt id, allowed categories, and lifecycle timestamps. +
- Even closed categories such as stress/travel are sensitive. Add retention/delete policy in this plan and do not treat them as harmless telemetry. +
MVP Detector Choice
+Use low_sleep as the first detector if settled sleep data is reliable enough in code. It is non-safety, understandable, common enough to validate UX, and less likely to conflict with illness-safety logic than autonomic or respiratory signals.
| Detector | Decision | Reason |
|---|---|---|
low_sleep |
+ First slice candidate | +Clear user-facing explanation; uses settled sleep data; non-safety; report context is easy to apply detector-specifically. | +
unusual_daytime_rest |
+ Follow-up detector | +Useful, but needs more careful segmentation and false-positive handling. | +
low_activity |
+ Follow-up detector | +Good candidate, but device coverage and illness/travel/recovery ambiguity need more handling. | +
high_autonomic_load |
+ Defer | +Intersects heavily with illness prodrome and stress flags. | +
respiratory_or_oxygen_shift |
+ Out of MVP | +Safety-sensitive. Validate basic prompt UX before asking about this class of signal. | +
State Model
+Use one tenant-local interaction table for MVP. It represents the detected signal, reservation, prompt lifecycle, and eventual answer.
+CREATE TABLE IF NOT EXISTS context_prompt_interactions (
+ prompt_id TEXT PRIMARY KEY,
+ signal_date DATE NOT NULL,
+ prompt_local_date DATE NOT NULL,
+ detected_reason TEXT NOT NULL,
+ detector_version TEXT NOT NULL,
+ status TEXT NOT NULL, -- detected | reserved | prompted | answered | skipped | expired | send_failed
+ category TEXT, -- NULL until answered/skipped
+ source TEXT, -- NULL until answer; telegram for MVP
+ prompt_message_id BIGINT,
+ prompted_at TIMESTAMPTZ,
+ expires_at TIMESTAMPTZ NOT NULL,
+ answered_at TIMESTAMPTZ,
+ allowed_categories JSONB NOT NULL DEFAULT '[]'::jsonb,
+ metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ UNIQUE (signal_date, detected_reason)
+);Add a partial unique index for one sent prompt per tenant-local prompt day:
+CREATE UNIQUE INDEX IF NOT EXISTS idx_context_prompt_one_sent_per_day
+ON context_prompt_interactions (prompt_local_date)
+WHERE status IN ('reserved', 'prompted', 'answered', 'skipped', 'expired', 'send_failed');-
+
sourceis an answer/source channel, not event identity.
+ categoryis nullable until answer.
+ signal_dateis the date of the metric anomaly.
+ prompt_local_dateis the local date on which the prompt is/was sent.
+ - Use
DATE, notTEXT, to prevent string/date confusion.
+
Prompt Lifecycle
+| Status | Meaning | Transitions |
|---|---|---|
detected | Signal exists but no prompt is reserved. | Optional; MVP may skip and reserve directly inside a transaction. |
reserved | Scheduler claimed the daily prompt slot before Telegram send. | prompted after send success; send_failed after send failure. |
prompted | Telegram prompt was sent and can be answered until expires_at. | answered, skipped, or expired. |
answered | User selected a concrete context category. | Terminal; repeated same callback is idempotent. |
skipped | User selected skip_context or unknown_context. | Terminal; suppresses future prompt for same signal. |
expired | Prompt lifetime elapsed. | Terminal for MVP; do not re-prompt same signal. |
send_failed | Reservation happened but Telegram send failed. | Terminal for MVP, or eligible for cleanup/retry only if explicitly implemented. |
Delivery policy: prefer rare missed prompts over duplicate prompts. The MVP should bias toward at-most-once prompt delivery.
+Telegram Callback Design
+-
+
- Callback payload shape:
ctx:<prompt_id>:<choice_code>, where both IDs are short and opaque enough to fit Telegram's 64-byte limit.
+ - Server loads the prompt by
prompt_idand validates tenant/chat ownership, status,expires_at, and allowed category set.
+ - Do not encode signal date, detector reason, or full category as callback identity. +
- Repeated webhook delivery is idempotent. A second click on the same final category returns an ack without rewriting timestamps. +
- Double-clicking different categories after a final answer must not change the stored category in MVP. First valid answer wins. +
- If feature flag is disabled after prompt send but before answer, accept already-sent prompt answers unless a separate kill switch requires hard rejection. +
MVP Bot UX
+
+
+
+
+
+
+ Prompt
+Sleep was unusually short
+Your latest sleep was well below your usual range. What context should be noted?
+ +
+
+
+
+ Acknowledgement
+Saved for future reports.
+
+
+
+
+ Future report caveat
+Sleep context: stress.
+This explains the low-sleep detector only; other health signals are evaluated normally.
+Report Semantics
+-
+
- Answers apply to future reports only. MVP does not edit an already-sent Telegram report. +
- Acknowledgement text should say "Saved for future reports" to avoid implying the current report changed. +
- No pending caveat for non-safety MVP signals. Pending caveats add anxiety without user value. +
- Context is detector-specific: "Sleep context: travel" or "Activity context: recovery", not "this whole day is incomparable". +
- Future baseline exclusion must also be metric/detector-specific and requires a separate plan. MVP does not exclude annotations from baselines. +
Feature Flags and Kill Switches
+-
+
proactive_context_prompts: controls sending new prompts. Default false.
+ context_caveats_enabled: controls report rendering of saved context caveats. Default false.
+ - Disabling prompt sending does not delete stored rows and does not reject already-sent prompt answers unless explicitly configured. +
- Disabling caveats hides context in reports without affecting prompt lifecycle storage. +
Reliability Scenarios
+| Scenario | Expected MVP behavior |
|---|---|
| Two scheduler runs in parallel | Unique constraints allow at most one reservation and one prompt-local-date slot. |
| Crash after reservation before Telegram send | Row remains reserved and occupies the daily prompt slot. No duplicate prompt. |
| Telegram send succeeds but status update fails | Prefer no re-send. Log loudly; row may need admin cleanup. Avoid duplicate UX. |
| Telegram send fails | Mark send_failed if possible; send_failed occupies the daily prompt slot and is terminal in MVP. |
| Repeated webhook delivery | Idempotent ack, no timestamp/category churn. |
| Double tap different buttons | First valid final answer wins; second receives neutral ack. |
| Feature flag disabled after send | Already-sent answer is accepted unless a hard kill switch is added later. |
Retention and Deletion
+-
+
- MVP retention is 180 days by default via
context_prompt_retention_days, clamped to 30-730 days. Daily maintenance deletes older interaction rows.
+ - Numeric metadata should be minimal and derivable. Do not store raw metric series in annotations. +
- Provide a future deletion path per tenant/date/detected_reason; dashboard/admin editing is a separate issue. +
- Issue/PR/docs must not include real user examples. +
Files Likely to Change
+-
+
internal/storage/context_prompt.go- DDL, state machine, reservation, answer save, expiry, cleanup helpers.
+ internal/storage/context_prompt_test.go- state transitions, uniqueness, metadata allowlist, reliability scenarios.
+ internal/storage/context_anomaly.go- low-sleep detector and detector registry contract.
+ internal/notify/context_prompt.go- Telegram prompt rendering, callback parsing, ack text.
+ internal/notify/checkin_callback.goor new webhook dispatcher - routecheckin:andctx:prefixes safely.
+ internal/notify/report.goandinternal/notify/report_rich.go- future-report detector-specific caveat rendering, behind kill switch.
+ internal/health/i18n_en.go,internal/health/i18n_ru.go,internal/health/i18n_sr.go- prompt labels, choices, acknowledgements, future caveats.
+ cmd/server/main.go- startup DDL and scheduler/webhook wiring.
+ AGENTS.mdandCLAUDE.mdonly if durable architecture instructions are added; mirror both files.
+
Implementation Steps
+-
+
- Add storage schema and constants for statuses, categories, detected reasons, and feature flags. +
- Add reservation transaction: choose eligible low-sleep signal, enforce uniqueness, create
reservedrow withprompt_id,prompt_local_date,expires_at, and allowed categories.
+ - Add Telegram send path that turns
reservedintopromptedonly after send success.
+ - Add callback handler for
ctx:payloads with tenant/chat ownership, expiry, allowed-category validation, and first-answer-wins idempotency.
+ - Add low-sleep detector with conservative threshold and enough settled-data checks. +
- Add report caveat rendering for answered/skipped context only when
context_caveats_enabledis true.
+ - Add cleanup/expiry for stale prompted/reserved rows. +
- Update this plan with actual implementation notes and verification after approval and code completion. +
Test Plan
+-
+
go test ./internal/storage -run Context -count=1
+ go test ./internal/notify -run Context -count=1
+ go test ./internal/notify -run Checkin -count=1to prove existing check-in callbacks still work.
+ go test ./internal/health -run Illness -count=1to prove illness logic is unchanged.
+ go test ./internal/notify ./internal/storage ./internal/health -count=1
+ - DB-backed smoke if a test DB is configured: DDL, uniqueness, reservation race, answer idempotency, expiry, metadata allowlist. +
Required Test Scenarios
+-
+
- Two concurrent scheduler attempts reserve only one prompt. +
- Same signal from a later source cannot create a second event row. +
- One sent prompt per prompt-local-date. +
- Callback for yesterday's signal is valid if prompt is not expired. +
- Expired prompt rejects answer without mutation. +
- Category not in allowed set rejects answer. +
- Repeated webhook delivery is idempotent. +
- Double tap different categories keeps first answer. +
- Feature flag off prevents new prompts. +
- Context answer does not alter illness confidence or safety caps. +
Manual QA Checklist
+-
+
- Ordinary day: no prompt. +
- Low-sleep synthetic day: one prompt only. +
- Prompt answer ack says saved for future reports. +
- Current already-sent report is not edited. +
- Next report shows detector-specific caveat only when caveats are enabled. +
- Check-in prompt still triggers morning report when answered in time. +
- Context prompt answer never triggers a morning report. +
- Disabling prompt flag stops new prompts. +
- Disabling caveat flag hides report caveats. +
Rollout Metrics
+Define stop/go criteria before enabling beyond one tenant.
+| Metric | Go signal | Stop/revisit signal |
|---|---|---|
| Prompts per user per rolling 7 days | ≤ 2 prompts/user/7 days. | > 3 prompts/user/7 days or prompts on 3 consecutive days. |
| Response rate | ≥ 50% answered or skipped within 36h. | < 30% answered or skipped after at least 5 prompts. |
| Skip/unknown rate | ≤ 50% of answered prompts. | > 70% after at least 5 answers. |
| False ordinary-day prompt rate | 0 obvious false positives in manual review of first 5 prompts. | ≥ 1 obvious false positive pauses rollout. |
| Duplicate prompts | 0 duplicate prompt messages per prompt-local-date. | Any duplicate is a blocker. |
| Expired callbacks | ≤ 30% of sent prompts expire unanswered. | > 50% after at least 5 prompts. |
| Illness safety changes | 0 context-driven changes to illness confidence, caps, or EnergyBank safety overrides. | Any context-driven safety change is a blocker. |
Risks and Mitigations
+-
+
- State mismatch: explicit statuses and nullable category fix awaiting-classification modeling. +
- Duplicate prompts: unique constraints, reservation transaction, and at-most-once policy. +
- Wrong stale callback semantics: prompt expiry is based on
expires_at, not signal date equals today.
+ - UX fatigue: one detector, one prompt per day, rolling cooldown, and stop/go metrics. +
- Safety conflict: non-safety MVP detector and regression tests around illness caps. +
- Privacy leak: closed enums, no free text, metadata allowlist, retention policy. +
- Over-broad context: detector-specific caveats only. +
Rollout Plan
+-
+
- Merge code with both
proactive_context_prompts=falseandcontext_caveats_enabled=false.
+ - Deploy and verify DDL, webhook routing, and no prompt sends while disabled. +
- Enable prompt sending for one tenant only. +
- Review rollout metrics after a fixed small window, for example 7-14 days or at least 3 eligible prompts. +
- Enable caveats only after prompt lifecycle is clean and duplicate rate is zero. +
- Do not add second detector until first detector meets stop/go criteria. +
Rollback Plan
+-
+
- Disable
proactive_context_promptsto stop new prompts.
+ - Disable
context_caveats_enabledto hide report caveats.
+ - Stored rows remain until the 180-day default retention job prunes them, unless the operator manually deletes rows earlier. +
- No readiness or EnergyBank recalculation is required because MVP does not change scoring. +
Out of Scope
+-
+
- Respiratory/oxygen prompts. +
- High-autonomic-load prompts. +
- Dashboard/admin editing of annotations. +
- Editing already-sent Telegram reports. +
- Sending context to Gemini. +
- Automatic baseline exclusion. +
- Free-text explanations. +
Resolved Decisions and Follow-Ups
+-
+
- First detector:
low_sleep.
+ - Low-sleep threshold:
sleep_total <= 6.0hand z-score<= -1.5against at least 14 valid prior baseline days in the last 30 days.
+ - Sleep data quality gate: reject target and baseline days with
sleep_total < 3.0hascapture_gap.
+ - Source-conflict gate: reject target and baseline days when another source in the same normalized sleep day is at least 2h higher and reaches
max(6.0h, baseline_avg - 1.0h). The detector does not decide which source is correct; material disagreement suppresses the prompt.
+ - Prompt-usefulness gate: after candidate detection, veto if there is a recent equivalent prompt, wake-date
sicksubjective check-in for the analyzed sleep, or moderate/high illness suspicion.
+ - Prompt-usefulness positive evidence: strong anomaly (
sleep_total <= 4.5hor z-score<= -2.5), disrupted sleep structure/awake time, or at least 2 short nights in the last 3 days. Timing evidence is disabled in MVP until a source-qualified timing extractor exists.
+ - Usefulness evidence cannot rescue a candidate rejected by
capture_gap,source_conflict, baseline warmup, or another candidate-quality reason.
+ - Prompt expiry: 36 hours after prompt reservation/send attempt. +
- Retention: default 180 days, configurable via
context_prompt_retention_daysand clamped to 30-730 days.
+ - Follow-up: add admin/SQL rollout dashboard before enabling beyond the first tenant. +
Implementation Result
+-
+
- Added
context_prompt_interactionswith opaqueprompt_id, separatesignal_date/prompt_local_date, nullablecategory, explicit lifecycle statuses, allowed-category JSON, and metadata allowlist.
+ - Added startup DDL wiring for legacy mode, existing tenants, newly created tenants, and the tenant manager provisioning path. +
- Implemented the first detector as
low_sleep_v2: requires at least 14 valid prior baseline days,sleep_total <= 6.0h, and z-score<= -1.5against the prior 30-day valid sleep baseline.
+ - Added merge-gate sleep quality guards:
capture_gapfor selected sleep below 3h, andsource_conflictfor material same-day source disagreement. The same predicate filters baseline days before computing average and standard deviation.
+ - Added separate prompt-usefulness gate: it vetoes recent equivalent prompts, wake-date
sickcheck-ins for the analyzed sleep, and moderate/high illness flow; it requires at least one usefulness signal such as strong anomaly (sleep_total <= 4.5hor z-score<= -2.5), awake/efficiency disruption, or repeated short-night trend.
+ - Disabled timing deviation as send evidence for MVP because raw timing rows can mix sources after candidate source-quality checks. Re-enable only with a source-qualified timing extractor. +
- Candidate quality remains first in the pipeline: sleep structure evidence is evaluated only after
low_sleep_v2has passed coverage/source-quality checks, and tests pin that usefulness evidence cannot bypass a rejected candidate.
+ - Context prompt callbacks now accept both
promptedandreservedrows, so a Telegram send that succeeds before the sent-status DB update fails does not leave a delivered button unanswerable.
+ - Context prompt reservation/send runs after the morning report send mutex is released. Prompt dedupe relies on
context_prompt_interactionsuniqueness instead of holding the morning report lock.
+ - Added post-morning-report prompt sending behind
settings.proactive_context_prompts. The prompt is reserved before send, markssend_failedon Telegram failure, and uses at-most-once semantics.
+ - Added Telegram callback format
ctx:<prompt_id>:<choice_code>. It does not include signal date, detector reason, category names, or any real-world event details.
+ - Extended the webhook router to handle context answers separately from subjective check-ins. Context answers do not trigger morning reports and expire via
expires_at.
+ - Added future-report context caveats behind
settings.context_caveats_enabled. Caveats are attached after illness suspicion and safety caps, so context cannot lower illness confidence or remove safety caps.
+ - Made
send_failedterminal for MVP and part of the one-prompt-per-local-day dedupe constraint.
+ - Kept callbacks accepted after prompt delivery even when
proactive_context_promptsis later disabled; the flag stops new sends, not answers to already delivered prompts.
+ - Added 180-day default retention with daily pruning and
context_prompt_retention_daysbounds.
+ - Added English, Russian, and Serbian copy for prompt text, button labels, callback acknowledgements, and report caveats. +
Checks Run
+-
+
gofmton all touched Go files.
+ go test ./internal/storage ./internal/notify ./internal/health
+ go test ./cmd/server
+ go test ./...
+ - Real DB dry-run on schema
health: before guards, 8 potential prompt days in the last 180 days; after guards, 4. Since the broader retrospective start, after guards, 18. With timing evidence disabled for MVP, prompt-usefulness sends 3 of the 4 last-180-day candidates; one low-usefulness candidate is rejected by the policy gate, and the known manually reviewed historical outlier remainsno_trigger.
+
Known Limitations
+-
+
- No live database race test was added; the project already uses structural DDL tests for this layer. Race prevention relies on SQL uniqueness plus transactional answer updates. +
- Retention now has a default prune path, but there is still no user-facing deletion UI. +
- There is no admin UI for prompt metrics yet. Rollout should use SQL until a later observability slice. +
- The first detector uses a conservative hybrid threshold plus source-quality guards. It should be reviewed after real prompt volume is observed. +
Approval Gate
+Approved in chat on 2026-06-20. Implementation completed on branch codex/185-proactive-context-prompts. Do not enable proactive_context_prompts or context_caveats_enabled in production until the deployment checklist and rollout owner approve the tenant-level rollout.