123 lines
6.0 KiB
Markdown
123 lines
6.0 KiB
Markdown
# 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](01-memory-streak.md) | ~180 | 3-4 | Daily streak counter in StatusBar; resets if 24h gap |
|
|
| 2 | [Daily Brief](02-daily-brief.md) | ~330 | 5-6 | Morning notification summarising yesterday + today suggestion |
|
|
| 3 | [Continuity Banner](03-continuity-banner.md) | ~140 | 2-3 | "Picking up where you left off" banner on Chat re-open |
|
|
| 4 | [Weekly Wins Digest](04-weekly-wins-digest.md) | ~340 | 4-5 | Monday card: frames saved, recalls, est. minutes saved |
|
|
| 5 | [Milestone Cards](05-milestone-cards.md) | ~200 | 2-3 | Confetti + congrats at 1/10/100/1000 frames |
|
|
| 6 | [Tour Replay](06-tour-replay.md) | ~60 | 1-1.5 | Settings button to re-trigger post-wizard coachmark sequence |
|
|
| 7 | [Pending Imports Reminder](07-pending-imports-reminder.md) | ~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.
|