waggle-os/docs/addiction-features

Addiction Features — Block B Design Docs (2026-05-01)

Purpose: Set of seven design-stage docs covering the "addiction features" cluster from the 2026-05-01 PM walkthrough brief. Each doc is design-only — no code shipped yet. Marko ratifies per feature (GO / MODIFY / SKIP) before CC implements.

Status: AWAITING_RATIFICATION — all 7 docs pending Marko review.

Scope: Loops that get users to come back tomorrow. Quantified-value reinforcement (streaks, weekly digests), pickup affordances (continuity banner, daily brief), milestone celebrations, replayable onboarding, gentle-nudge import prompts.

---

Index

#	Feature	LOC est.	Hours est.	One-line summary
1	Memory Streak	~180	3-4	Daily streak counter in StatusBar; resets if 24h gap
2	Daily Brief	~330	5-6	Morning notification summarising yesterday + today suggestion
3	Continuity Banner	~140	2-3	"Picking up where you left off" banner on Chat re-open
4	Weekly Wins Digest	~340	4-5	Monday card: frames saved, recalls, est. minutes saved
5	Milestone Cards	~200	2-3	Confetti + congrats at 1/10/100/1000 frames
6	Tour Replay	~60	1-1.5	Settings button to re-trigger post-wizard coachmark sequence
7	Pending Imports Reminder	~130	2	Memory-app banner for users who skipped import
	Totals	~1,380 LOC	~20-25h	All seven shipped

---

Cross-feature decisions Marko needs to make once

These appear in multiple docs and benefit from a single ruling:

1. What counts as a "frame"?

   • Used by: Streak (#1), Milestones (#5), Wins Digest (#4)
   • Options: (a) all frames, (b) non-deprecated only, (c) non-deprecated AND non-temporary, (d) importance ≥ normal
   • Recommendation: (c) — count non-deprecated, non-temporary. Aligns with existing composeWorkspaceSummary filter.

2. Notification timezone strategy

   • Used by: Streak (#1, day boundary), Daily Brief (#2, fire hour), Wins Digest (#4, week boundary)
   • Options: (a) server-local TZ for v1 + document, (b) per-user TZ from settings, (c) detect from browser
   • Recommendation: (a) v1, (b) v2 if cross-TZ usage emerges.

3. Empty-state behaviour for fresh users

   • Used by: Streak (#1, day-1 user), Daily Brief (#2, no yesterday), Continuity (#3, no last session), Wins Digest (#4, < 7 days history)
   • Options: (a) suppress entirely, (b) show educational copy, (c) show motivational copy
   • Recommendation: (a) suppress — fresh users have higher-priority surfaces (wizard, Tour).

4. Banner / overlay z-index hierarchy

   • Three new surfaces (Continuity, Daily Brief, Imports Reminder) plus existing OnboardingTooltips, LoginBriefing, MilestoneCard.
   • Need a documented ordering rule. Recommendation: only ONE high-priority overlay can render at once; the rest queue.

5. LLM cost approval

   • Daily Brief generator: ~$0.005/user/day = $0.15/user/month
   • Wins Digest theme extraction: ~$0.01/user/week = $0.04/user/month
   • Total: ~$0.19/user/month for both. Per-user margin impact on FREE tier: minor; on PRO: negligible.

---

Ratification checklist

Marko, please mark each feature with one of: GO (build as designed), MODIFY (open the doc, leave inline comments), SKIP (defer or kill).

• #1 Memory Streak — GO / MODIFY / SKIP
• #2 Daily Brief — GO / MODIFY / SKIP
• #3 Continuity Banner — GO / MODIFY / SKIP
• #4 Weekly Wins Digest — GO / MODIFY / SKIP
• #5 Milestone Cards — GO / MODIFY / SKIP
• #6 Tour Replay — GO / MODIFY / SKIP
• #7 Pending Imports Reminder — GO / MODIFY / SKIP

Plus the cross-feature decisions:

• Frame inclusion rule
• Timezone strategy v1
• Empty-state behaviour (suppress / educate / motivate)
• Overlay z-index queue rule
• LLM cost approval ($0.19/user/month for #2 + #4)

---

Build order recommendation (assuming all GO)

CC's recommended sequencing (each phase ships independently, no blockers between them):

Phase 1 — Quick wins (2-3h, low risk, immediate user-visible)

• #6 Tour Replay (~1.5h)
• #7 Pending Imports Reminder (~2h)

Phase 2 — Streak loop (3-4h)

• #1 Memory Streak (single SQLite addition + StatusBar wire)

Phase 3 — Celebration (2-3h)

• #5 Milestone Cards (uses same frame-count signal as Streak)

Phase 4 — Continuity surface (2-3h)

• #3 Continuity Banner (uses existing recentThreads from workspace-context)

Phase 5 — Daily Brief (5-6h, LLM cost approval gate)

• #2 Daily Brief (cron job + LLM generator + Tauri notification permission)

Phase 6 — Weekly Wins (4-5h, recall instrumentation gate)

• #4 Weekly Wins Digest (requires HybridSearch instrumentation — heaviest)

Total parallel-friendly: Phases 1+2+3 can ship together (~8h). Phase 4 independent. Phases 5+6 require backend work + LLM approval.

---

Out of scope for this design pass

• Tier-gated variants (does FREE see streak chip? does PRO see different milestone copy?). Defer to per-feature MODIFY notes once Marko ratifies each.
• Localization. v1 ships English-only copy.
• A/B testing infrastructure for which copy variants drive engagement. Wait for usage data.
• Cross-feature combo bonuses ("Streak + 100 frames = bonus card"). Wait until each individual feature ships.

---

Implementation contract

Once Marko ratifies (per-feature GO), CC will:

1. Open the corresponding doc, drop a ## Implementation log section at the bottom, link the eventual commits there.
2. Implement in the recommended phase order unless Marko prefers a different order.
3. After each phase, halt and PM Pass for verification before starting the next.
4. Each phase commits include the feature number in the message (feat(streak): ship #1 Memory Streak counter) for backlink.

No feature ships before its doc has GO from Marko.