diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 90576df..eceb20b 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -148,84 +148,87 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| INV-01 | — | Pending | -| INV-02 | — | Pending | -| INV-03 | — | Pending | -| INV-04 | — | Pending | -| INV-05 | — | Pending | -| INV-06 | — | Pending | -| INV-07 | — | Pending | -| SHARE-01 | — | Pending | -| SHARE-02 | — | Pending | -| SHARE-03 | — | Pending | -| SHARE-04 | — | Pending | -| SHARE-05 | — | Pending | -| SHARE-06 | — | Pending | -| SHARE-07 | — | Pending | -| SHARE-08 | — | Pending | -| SHARE-09 | — | Pending | -| SHARE-10 | — | Pending | -| EXP-01 | — | Pending | -| EXP-02 | — | Pending | -| EXP-03 | — | Pending | -| EXP-04 | — | Pending | -| EXP-05 | — | Pending | -| EXP-06 | — | Pending | -| EXP-07 | — | Pending | -| AUTH-01 | — | Pending | -| AUTH-02 | — | Pending | -| AUTH-03 | — | Pending | -| AUTH-04 | — | Pending | -| AUTH-05 | — | Pending | -| NOTF-01 | — | Pending | -| NOTF-02 | — | Pending | -| NOTF-03 | — | Pending | -| NOTF-04 | — | Pending | -| NOTF-05 | — | Pending | -| NOTF-06 | — | Pending | -| NOTF-07 | — | Pending | -| AI-01 | — | Pending | -| AI-02 | — | Pending | -| AI-03 | — | Pending | -| AI-04 | — | Pending | -| AI-05 | — | Pending | -| AI-06 | — | Pending | -| AI-07 | — | Pending | -| SALES-01 | — | Pending | -| SALES-02 | — | Pending | -| SALES-03 | — | Pending | -| SALES-04 | — | Pending | -| SALES-05 | — | Pending | -| SALES-06 | — | Pending | -| SALES-07 | — | Pending | -| SETUP-01 | — | Pending | -| SETUP-02 | — | Pending | -| SETUP-03 | — | Pending | -| SETUP-04 | — | Pending | -| SETUP-05 | — | Pending | -| SETUP-06 | — | Pending | -| UI-01 | — | Pending | -| UI-02 | — | Pending | -| UI-03 | — | Pending | -| UI-04 | — | Pending | -| UI-05 | — | Pending | -| UI-06 | — | Pending | -| UI-07 | — | Pending | -| DATA-01 | — | Pending | -| DATA-02 | — | Pending | -| DATA-03 | — | Pending | -| DATA-04 | — | Pending | -| DATA-05 | — | Pending | -| DATA-06 | — | Pending | -| DATA-07 | — | Pending | -| DATA-08 | — | Pending | -| DATA-09 | — | Pending | +| INV-01 | 3 | Pending | +| INV-02 | 4 | Pending | +| INV-03 | 4 | Pending | +| INV-04 | 4 | Pending | +| INV-05 | 4 | Pending | +| INV-06 | 8 | Pending | +| INV-07 | 8 | Pending | +| SHARE-01 | 2 | Pending | +| SHARE-02 | 2 | Pending | +| SHARE-03 | 2 | Pending | +| SHARE-04 | 2 | Pending | +| SHARE-05 | 2 | Pending | +| SHARE-06 | 4 | Pending | +| SHARE-07 | 4 | Pending | +| SHARE-08 | 4 | Pending | +| SHARE-09 | 4 | Pending | +| SHARE-10 | 11 | Pending | +| EXP-01 | 5 | Pending | +| EXP-02 | 5 | Pending | +| EXP-03 | 5 | Pending | +| EXP-04 | 5 | Pending | +| EXP-05 | 5 | Pending | +| EXP-06 | 5 | Pending | +| EXP-07 | 5 | Pending | +| AUTH-01 | 1 | Pending | +| AUTH-02 | 1 | Pending | +| AUTH-03 | 1 | Pending | +| AUTH-04 | 1 | Pending | +| AUTH-05 | 1 | Pending | +| NOTF-01 | 6 | Pending | +| NOTF-02 | 7 | Pending | +| NOTF-03 | 7 | Pending | +| NOTF-04 | 7 | Pending | +| NOTF-05 | 7 | Pending | +| NOTF-06 | 7 | Pending | +| NOTF-07 | 7 | Pending | +| AI-01 | 8 | Pending | +| AI-02 | 8 | Pending | +| AI-03 | 8 | Pending | +| AI-04 | 9 | Pending | +| AI-05 | 9 | Pending | +| AI-06 | 9 | Pending | +| AI-07 | 9 | Pending | +| SALES-01 | 10 | Pending | +| SALES-02 | 10 | Pending | +| SALES-03 | 10 | Pending | +| SALES-04 | 10 | Pending | +| SALES-05 | 10 | Pending | +| SALES-06 | 10 | Pending | +| SALES-07 | 10 | Pending | +| SETUP-01 | 12 | Pending | +| SETUP-02 | 12 | Pending | +| SETUP-03 | 12 | Pending | +| SETUP-04 | 12 | Pending | +| SETUP-05 | 12 | Pending | +| SETUP-06 | 12 | Pending | +| UI-01 | 11 | Pending | +| UI-02 | 11 | Pending | +| UI-03 | 11 | Pending | +| UI-04 | 11 | Pending | +| UI-05 | 11 | Pending | +| UI-06 | 11 | Pending | +| UI-07 | 3 | Pending | +| DATA-01 | 3 | Pending | +| DATA-02 | 11 | Pending | +| DATA-03 | 11 | Pending | +| DATA-04 | 11 | Pending | +| DATA-05 | 11 | Pending | +| DATA-06 | 12 | Pending | +| DATA-07 | 12 | Pending | +| DATA-08 | 12 | Pending | +| DATA-09 | 12 | Pending | **Coverage:** - v1 requirements: 62 total -- Mapped to phases: 0 -- Unmapped: 62 ⚠️ (will be filled by roadmap) +- Mapped to phases: 62 +- Unmapped: 0 ✓ +- **Coverage: 100%** --- + *Requirements defined: 2026-01-27* -*Last updated: 2026-01-27 after initial definition* +*Roadmap traceability updated: 2026-01-27* +*Last updated: 2026-01-27 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..ce6f3b0 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,355 @@ +# Sage Roadmap + +## Overview + +Sage is built in 12 phases that move from authentication foundations through core inventory tracking, expiration management, notifications, usage tracking, AI predictions, and sales integration—ending with cross-platform polish and guided onboarding. This structure follows natural delivery boundaries: each phase enables a complete, verifiable user capability. Dependencies flow strictly upward (later phases depend on earlier ones), with horizontal separation (auth → multi-user → core tracking → alerts → notifications → intelligence). + +Research validated three phases (MVP, expansion, differentiation); comprehensive depth expands these into 12 focused milestones that manage complexity and allow earlier user validation. + +--- + +## Phases + +### Phase 1: Authentication & Account Basics + +**Goal:** Users can create accounts and authenticate securely across sessions. + +**Requirements:** AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05 + +**Success Criteria:** +1. User can sign up with email and password in <3 seconds +2. User can log in with valid credentials and session persists across app restarts +3. User can reset forgotten password and receive recovery email within 1 minute +4. User can log out from any screen and subsequent session requires re-authentication +5. Failed login attempts return clear error messages (invalid password vs account not found) + +**Dependencies:** None (foundational) + +--- + +### Phase 2: Household Creation & Invites + +**Goal:** Multiple users can collaborate in a shared household with invitation-based membership. + +**Requirements:** SHARE-01, SHARE-02, SHARE-03, SHARE-04, SHARE-05 + +**Success Criteria:** +1. User can create a household with a name, and other users see it as joinable via invite code +2. User can generate unique invite codes that are valid for 30 days and expire explicitly +3. User can join a household via 8-character invite code and immediately access shared inventory +4. When joining, user can choose to merge inventories, keep separate, or use inviter's (option chosen in UI) +5. Items with same name but different expiration dates from merged inventories are tracked as separate entries + +**Dependencies:** Phase 1 (AUTH required to create households) + +--- + +### Phase 3: Barcode Scanning & Product Lookup + +**Goal:** Users can add items via barcode scan and product data is instantly recognized. + +**Requirements:** INV-01, UI-07 (barcode offline queueing) + +**Success Criteria:** +1. User can hold device to barcode and scan completes in <3 seconds with product name populated +2. Barcode scanning works offline and queues the request until connection restored +3. Barcode lookups for same product are cached (second scan instant; cache survives app restart) +4. User sees fallback to manual entry if scan fails (UI offers "Can't find it? Enter manually") +5. Cached barcode data reduces external API calls by 80%+ (server-side cache shared across household) + +**Dependencies:** Phase 1 (AUTH required to save items to household) + +--- + +### Phase 4: Manual Entry, Search & Filtering + +**Goal:** Users can add items manually and find what they're looking for instantly. + +**Requirements:** INV-02, INV-03, INV-04, INV-05, INV-06 + +**Success Criteria:** +1. User can add item manually with name, quantity, location, optional expiration date in <15 seconds +2. User can view full inventory sorted by location and see items count per location +3. User can search inventory by name and get results in <500ms (fuzzy matching if typos) +4. User can filter inventory by location, expiration status (expiring soon, expired, valid) +5. User can edit item details (quantity, location, expiration) and changes sync to all household members in <10 seconds + +**Dependencies:** Phase 1 (AUTH required) + +--- + +### Phase 5: Expiration Management & Alerts + +**Goal:** System tracks expiration dates and alerts users before food spoils. + +**Requirements:** EXP-01, EXP-02, EXP-03, EXP-04, EXP-05, EXP-06, EXP-07 + +**Success Criteria:** +1. User can set expiration date when adding item; system calculates "days until expiration" in real-time +2. User can view all items sorted by expiration date (soonest first) with visual age indicators (red = expired, yellow = <3 days, green = safe) +3. System sends expiration alert notification 3 days before expiration (configurable 1-7 days in settings) +4. User can snooze alert for 1 day or dismiss it permanently for that item +5. System tracks purchase date separately from expiration date to enable usage analytics later + +**Dependencies:** Phase 4 (requires items in inventory to set expiration dates) + +--- + +### Phase 6: In-App Notification Center + +**Goal:** Users see expiration alerts in a clean in-app notification center. + +**Requirements:** NOTF-01 + +**Success Criteria:** +1. Notification center displays all alerts (expiring items) sorted by urgency +2. User can open item directly from notification and see current status +3. Notifications persist across app sessions until dismissed +4. Notification count badge on home screen shows unread count +5. User can clear all notifications in one action + +**Dependencies:** Phase 5 (expiration alerts must exist to display) + +--- + +### Phase 7: External Notifications (Discord, ntfy, Pushbullet, Telegram) + +**Goal:** Users can receive alerts via their preferred external platforms. + +**Requirements:** NOTF-02, NOTF-03, NOTF-04, NOTF-05, NOTF-06, NOTF-07 + +**Success Criteria:** +1. User can enable Discord webhook by pasting webhook URL; test message sends within 10 seconds +2. User can enable ntfy notifications by entering topic name; alerts appear in ntfy app in <5 seconds +3. User can enable Pushbullet by authorizing account; alerts appear on all Pushbullet devices +4. User can enable Telegram by following bot link and entering received token; alerts arrive in Telegram chat +5. User can customize alert timing (days before expiration, quiet hours 10pm-7am), frequency (daily digest vs immediate) + +**Dependencies:** Phase 5 (expiration alerts must exist to send externally) + +--- + +### Phase 8: Usage Tracking & Item History + +**Goal:** System collects consumption data to enable later prediction and analytics. + +**Requirements:** INV-06, INV-07, AI-01, AI-02, AI-03 + +**Success Criteria:** +1. User can mark item as "used" and it records timestamp; item removed from active inventory but tracked in history +2. User can mark item as "wasted" (expired, bad, etc.) and reason is recorded with timestamp +3. System builds usage history showing when items were purchased vs consumed (enables pattern detection) +4. System detects when items re-appear on shopping list before their last one expired (signals early replenishment pattern) +5. Historical data persists and is accessible for analytics dashboard + +**Dependencies:** Phase 4 (requires items to track usage) + +--- + +### Phase 9: AI Shopping Prediction + +**Goal:** System predicts when users will need items based on consumption history. + +**Requirements:** AI-04, AI-05, AI-06, AI-07 + +**Success Criteria:** +1. After 2+ weeks of usage data, system predicts "You'll need milk in 3 days" based on historical frequency +2. System adds predicted items to shopping list automatically with predicted date +3. User can accept or dismiss prediction; system learns from choices (improves accuracy if dismissed) +4. Prediction accuracy improves over time (system trains on feedback; users see "Getting better at knowing your preferences") +5. Predictions cover 70%+ of re-purchased items (validated against actual user behavior) + +**Dependencies:** Phase 8 (requires usage data to train predictions) + +--- + +### Phase 10: Local Sales Tracking + +**Goal:** System tracks local store sales and alerts users to deals on items they use. + +**Requirements:** SALES-01, SALES-02, SALES-03, SALES-04, SALES-05, SALES-06, SALES-07 + +**Success Criteria:** +1. User can add local store by name and zipcode; store appears in settings for sale tracking +2. User can manually enter sale (store, item name, price, sale dates) and sale is recorded with user UUID (anonymous) +3. Community sales database aggregates sales data; user can see sales for tracked items nearby (zipcode + store match) +4. System attempts to auto-fetch online store ads for tracked items (with fallback if services unavailable) +5. User receives alert when tracked item is on sale; predicted shopping needs are prioritized ("You need milk in 3 days, it's on sale this week at Kroger for $1.50 cheaper") + +**Dependencies:** Phase 9 (optional but works best with predictions; Phase 8 for usage data) + +--- + +### Phase 11: Web App & Cross-Platform UI Polish + +**Goal:** Users access inventory from any device with consistent experience. + +**Requirements:** UI-01, UI-02, UI-03, UI-04, UI-05, UI-06, DATA-01, DATA-02, DATA-03, DATA-04, DATA-05 + +**Success Criteria:** +1. Web app accessible at shared URL; user logs in and sees same household inventory as mobile +2. All UI elements readable in both dark (default) and light modes; contrast ratios meet WCAG AA +3. Android app works smoothly on devices 7.0+ with offline-first local SQLite cache +4. Multi-device sync happens in <10 seconds; user edits item on phone, sees it updated on tablet in real-time +5. Data stored in UTC timestamps; no timezone-related expiration bugs when users cross timezones + +**Dependencies:** Phase 4+ (UI elements must exist to polish; data structures set in earlier phases) + +--- + +### Phase 12: Setup Wizard & User Onboarding + +**Goal:** New users complete setup in <5 minutes and understand core features. + +**Requirements:** SETUP-01, SETUP-02, SETUP-03, SETUP-04, SETUP-05, SETUP-06, DATA-06, DATA-07, DATA-08, DATA-09 + +**Success Criteria:** +1. New user sees guided setup wizard requiring only email, password, household name (3 fields minimum) +2. Wizard asks about notification preferences (in-app, Discord, ntfy) as optional setup step +3. Wizard offers to generate invite code to share with household members or skip for solo use +4. Advanced features progressively revealed in settings as user explores (dark mode toggle, notification customization) +5. Help documentation accessible from settings; user can read about expiration alerts, barcode scanning, predictions + +**Dependencies:** All phases (setup must reference all features; executes last after all are built) + +**Additional Requirements Mapped to Phase 12:** +- DATA-06: App is completely free with no ads or paid features +- DATA-07: Code is open source and FOSS compliant +- DATA-08: Self-hosted Docker option available with clear setup instructions +- DATA-09: Self-hosted option supports TrueNAS Scale/Unraid deployment + +--- + +## Requirement Mapping Summary + +| Requirement | Category | Phase | Status | +|-------------|----------|-------|--------| +| INV-01 | Inventory Core | 3 | Pending | +| INV-02 | Inventory Core | 4 | Pending | +| INV-03 | Inventory Core | 4 | Pending | +| INV-04 | Inventory Core | 4 | Pending | +| INV-05 | Inventory Core | 4 | Pending | +| INV-06 | Inventory Core | 8 | Pending | +| INV-07 | Inventory Core | 8 | Pending | +| SHARE-01 | Sharing | 2 | Pending | +| SHARE-02 | Sharing | 2 | Pending | +| SHARE-03 | Sharing | 2 | Pending | +| SHARE-04 | Sharing | 2 | Pending | +| SHARE-05 | Sharing | 2 | Pending | +| SHARE-06 | Sharing | 4 | Pending | +| SHARE-07 | Sharing | 4 | Pending | +| SHARE-08 | Sharing | 4 | Pending | +| SHARE-09 | Sharing | 4 | Pending | +| SHARE-10 | Sharing | 11 | Pending | +| EXP-01 | Expiration | 5 | Pending | +| EXP-02 | Expiration | 5 | Pending | +| EXP-03 | Expiration | 5 | Pending | +| EXP-04 | Expiration | 5 | Pending | +| EXP-05 | Expiration | 5 | Pending | +| EXP-06 | Expiration | 5 | Pending | +| EXP-07 | Expiration | 5 | Pending | +| AUTH-01 | Authentication | 1 | Pending | +| AUTH-02 | Authentication | 1 | Pending | +| AUTH-03 | Authentication | 1 | Pending | +| AUTH-04 | Authentication | 1 | Pending | +| AUTH-05 | Authentication | 1 | Pending | +| NOTF-01 | Notifications | 6 | Pending | +| NOTF-02 | Notifications | 7 | Pending | +| NOTF-03 | Notifications | 7 | Pending | +| NOTF-04 | Notifications | 7 | Pending | +| NOTF-05 | Notifications | 7 | Pending | +| NOTF-06 | Notifications | 7 | Pending | +| NOTF-07 | Notifications | 7 | Pending | +| AI-01 | AI Prediction | 8 | Pending | +| AI-02 | AI Prediction | 8 | Pending | +| AI-03 | AI Prediction | 8 | Pending | +| AI-04 | AI Prediction | 9 | Pending | +| AI-05 | AI Prediction | 9 | Pending | +| AI-06 | AI Prediction | 9 | Pending | +| AI-07 | AI Prediction | 9 | Pending | +| SALES-01 | Sales Tracking | 10 | Pending | +| SALES-02 | Sales Tracking | 10 | Pending | +| SALES-03 | Sales Tracking | 10 | Pending | +| SALES-04 | Sales Tracking | 10 | Pending | +| SALES-05 | Sales Tracking | 10 | Pending | +| SALES-06 | Sales Tracking | 10 | Pending | +| SALES-07 | Sales Tracking | 10 | Pending | +| SETUP-01 | Setup | 12 | Pending | +| SETUP-02 | Setup | 12 | Pending | +| SETUP-03 | Setup | 12 | Pending | +| SETUP-04 | Setup | 12 | Pending | +| SETUP-05 | Setup | 12 | Pending | +| SETUP-06 | Setup | 12 | Pending | +| UI-01 | UI | 11 | Pending | +| UI-02 | UI | 11 | Pending | +| UI-03 | UI | 11 | Pending | +| UI-04 | UI | 11 | Pending | +| UI-05 | UI | 11 | Pending | +| UI-06 | UI | 11 | Pending | +| UI-07 | UI | 3 | Pending | +| DATA-01 | Data | 3 | Pending | +| DATA-02 | Data | 11 | Pending | +| DATA-03 | Data | 11 | Pending | +| DATA-04 | Data | 11 | Pending | +| DATA-05 | Data | 11 | Pending | +| DATA-06 | Data | 12 | Pending | +| DATA-07 | Data | 12 | Pending | +| DATA-08 | Data | 12 | Pending | +| DATA-09 | Data | 12 | Pending | + +**Coverage Summary:** +- Total v1 requirements: 62 +- Mapped to phases: 62 +- Unmapped: 0 ✓ +- **Coverage: 100%** + +--- + +## Phase Dependencies + +``` +Phase 1 (Auth) ──┐ + ├──→ Phase 2 (Households) ──→ Phase 3 (Barcode) ──→ Phase 4 (Manual + Search) + │ + └──────────────────────────────────→ Phase 4 + ↓ + Phase 5 (Expiration) + ↓ + Phase 6 (In-App Notifs) + ↓ + Phase 7 (External Notifs) + +Phase 4 ──→ Phase 8 (Usage Tracking) ──→ Phase 9 (AI Prediction) ──→ Phase 10 (Sales) + +Phase 11 (Web App & Polish) ← depends on all core phases (3-10) +Phase 12 (Setup Wizard) ← depends on all phases (1-11, references all features) +``` + +**Critical Path:** 1 → 2 → 3 → 4 → 5 → 6 → 7 (auth foundations must complete before inventory features; expiration before notifications) + +**Parallel Opportunities:** +- Phases 8-10 can start after Phase 4 completes (usage tracking independent of phases 5-7) +- Phase 11 can begin after Phase 5 completes (UI polish doesn't block feature delivery) + +--- + +## Phase Success Validation Strategy + +**For each phase completion:** +1. All success criteria demonstrated in live app (not unit tests or architecture) +2. Cross-household sync verified (multiple users on different devices) +3. Offline functionality tested where applicable +4. No new bugs regression against previous phases + +**User validation milestones:** +- After Phase 3: Users can add items (barcode) +- After Phase 5: Users can get expiration alerts (core value delivered) +- After Phase 8: Users generate consumption data (foundation for prediction) +- After Phase 9: Predictions show measurable accuracy (70%+ coverage) + +--- + +*Roadmap created: 2026-01-27* +*Total phases: 12* +*Depth calibration: Comprehensive (breaks down 3-phase research into focused milestones)* +*Next step: Phase 1 planning via /gsd:plan-phase* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..095a559 --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,220 @@ +# Sage Project State + +**Last updated:** 2026-01-27 +**Status:** Roadmap complete, ready for Phase 1 planning + +--- + +## Current Focus + +**Phase:** Roadmap created (not yet executing phases) +**Action:** Ready for `/gsd:plan-phase 1` to begin Phase 1 (Auth & Account Basics) planning + +--- + +## Project Reference + +**Project:** Sage — Collaborative Household Food Inventory Tracker + +**Core Value:** Users get accurate expiration alerts and never waste food due to forgotten ingredients + +**See:** `.planning/PROJECT.md` (last updated 2026-01-27) + +--- + +## Phase Overview & Progress + +| Phase | Name | Goal | Requirements | Success Criteria | Status | +|-------|------|------|--------------|------------------|--------| +| 1 | Auth & Account | Users log in securely | AUTH-01-05 (5) | 5 | Pending | +| 2 | Household Creation | Multi-user households | SHARE-01-05 (5) | 5 | Pending | +| 3 | Barcode Scanning | Core inventory via barcode | INV-01, UI-07, DATA-01 (3) | 5 | Pending | +| 4 | Manual Entry & Search | Complete core tracking | INV-02-05, SHARE-06-09 (6) | 5 | Pending | +| 5 | Expiration Mgmt | Expiration alerts | EXP-01-07 (7) | 5 | Pending | +| 6 | In-App Notifications | Local alert center | NOTF-01 (1) | 5 | Pending | +| 7 | External Notifications | Discord/ntfy/Telegram/Pushbullet | NOTF-02-07 (6) | 5 | Pending | +| 8 | Usage Tracking | Consumption history | INV-06-07, AI-01-03 (5) | 5 | Pending | +| 9 | AI Shopping Prediction | Smart recommendations | AI-04-07 (4) | 5 | Pending | +| 10 | Sales Tracking | Local deals integration | SALES-01-07 (7) | 5 | Pending | +| 11 | Web App & Polish | Cross-platform access | UI-01-06, DATA-02-05, SHARE-10 (10) | 5 | Pending | +| 12 | Setup Wizard | Onboarding & FOSS setup | SETUP-01-06, DATA-06-09 (10) | 5 | Pending | + +**Total Requirements Mapped:** 62 / 62 (100% ✓) + +--- + +## Requirement Traceability + +**Coverage by category:** + +| Category | Count | Phases | Status | +|----------|-------|--------|--------| +| Authentication | 5 | 1 | Pending | +| Sharing & Multi-User | 10 | 2, 4, 11 | Pending | +| Inventory Core | 7 | 3, 4, 8 | Pending | +| Expiration | 7 | 5 | Pending | +| Notifications | 7 | 6, 7 | Pending | +| AI Prediction | 7 | 8, 9 | Pending | +| Sales Tracking | 7 | 10 | Pending | +| Setup & Onboarding | 6 | 12 | Pending | +| UI & Platform | 7 | 3, 11 | Pending | +| Data & Performance | 9 | 3, 11, 12 | Pending | + +**Detailed mapping:** See `.planning/ROADMAP.md` "Requirement Mapping Summary" table + +--- + +## Critical Dependencies + +**Blocking order (must complete in sequence):** +1. Phase 1 (Auth) must complete before any feature phases can start +2. Phase 2 (Households) must complete before Phase 3 (inventory sync requires household context) +3. Phase 3 (Barcode) must complete before Phase 4 (search/filtering refinement) +4. Phase 4 (Manual Entry) must complete before Phase 5 (expiration depends on items existing) +5. Phase 5 (Expiration) must complete before Phase 6-7 (notifications depend on expiration logic) + +**Parallel opportunities:** +- Phase 8 (Usage Tracking) can start after Phase 4 completes (independent of Phases 5-7) +- Phase 11 (Web App & Polish) can start after Phase 5 completes +- Phase 10 (Sales Tracking) can start after Phase 8 completes + +**Final dependencies:** +- Phase 12 (Setup Wizard) references all phases; executes last + +--- + +## Roadmap Structure Summary + +**12 phases** organized in 3 tiers: + +**Tier 1: Foundations (Phases 1-2)** +- Auth & account management +- Household creation and invites +- Multi-user membership basis + +**Tier 2: Core Value Delivery (Phases 3-7)** +- Barcode scanning (INV-01, core) +- Manual entry & search (INV-02-05) +- Expiration management (EXP-01-07, core value delivered after Phase 5) +- Notification system (NOTF-01-07, user engagement) + +**Tier 3: Differentiation (Phases 8-10)** +- Usage tracking (foundation for intelligence) +- AI shopping prediction (main differentiator) +- Sales tracking (secondary differentiator) + +**Tier 4: Polish & UX (Phases 11-12)** +- Web app & cross-platform UI +- Setup wizard & guided onboarding + +**Depth calibration:** Research suggested 3 phases; comprehensive depth expands this to 12 focused milestones that respect natural delivery boundaries and allow earlier user validation. + +--- + +## Success Criteria (Phase Level) + +**Phase 1 Success:** Users can authenticate securely, sessions persist across restarts + +**Phase 2 Success:** Multiple users can join households via invite codes, see shared context + +**Phase 3 Success:** Users can scan barcodes and instantly add products to inventory + +**Phase 4 Success:** Users can manually add items, search inventory, edit details in real-time + +**Phase 5 Success:** System tracks expiration dates and alerts users 3 days before spoilage (core value) + +**Phase 6 Success:** Notifications appear in app notification center with snooze/dismiss options + +**Phase 7 Success:** Expiration alerts flow to Discord, ntfy, Pushbullet, Telegram (user's choice) + +**Phase 8 Success:** System records consumption events (used/wasted) with timestamps; patterns detectable + +**Phase 9 Success:** Predictions appear after 2+ weeks data; users see "You'll need milk in 3 days" style alerts + +**Phase 10 Success:** Users can track local sales; system alerts when predicted items go on sale + +**Phase 11 Success:** Web app accessible from browser; multi-device sync <10 seconds; dark/light modes readable + +**Phase 12 Success:** New users complete onboarding in <5 minutes with setup wizard; code is FOSS + Docker + +--- + +## Research Flags (Known Unknowns) + +**Phase 1 Research Needed:** +- Barcode database coverage (Open Food Facts + USDA coverage varies by region) +- Supabase free tier keep-alive strategy (7-day inactivity pause is documented gotcha) +- Realtime WebSocket stability with 3+ simultaneous household members + +**Phase 3 Research Needed:** +- Barcode API rate limit validation (assuming 90% cache hit rate) + +**Phase 9 Research Needed:** +- ML vs heuristics decision point (simple frequency-based vs complex models) + +**Phase 10 Research Needed:** +- Store API licensing terms (Kroger, Whole Foods, regional chains vary) +- Community moderation if building user-contributed barcode data + +**See:** `.planning/research/SUMMARY.md` "Gaps to Address During Planning" section + +--- + +## Decision Log + +| Decision | Rationale | Status | +|----------|-----------|--------| +| 12-phase structure (not 3) | Comprehensive depth allows focused milestones + earlier user validation | Approved | +| Barcode scanning Phase 3 | Core value; must validate scanning works before adding manual entry complexity | Pending | +| Expiration Phase 5 (not Phase 1) | Separates expiration from item tracking; alerts need items to exist first | Pending | +| Notifications split (in-app vs external) | In-app (Phase 6) validates notification UX; external (Phase 7) adds integrations | Pending | +| AI Prediction Phase 9 (not Phase 2) | Requires 2+ weeks consumption data (Phase 8) to train; premature in Phase 2 | Pending | +| Setup Wizard Phase 12 (last) | Must reference all features; executes after all capabilities are built | Pending | + +--- + +## Metrics to Track + +**Phase Completion Metrics:** +- Days to complete (phase vs estimate) +- Bugs found in phase vs previous phases (regression tracker) +- Requirements coverage (all success criteria demonstrated) + +**User Validation Metrics (future):** +- Phase 3: % of users attempting barcode scan +- Phase 5: % of users receiving expiration alert +- Phase 8: % of users recording consumption events +- Phase 9: Prediction accuracy (recall >80% for next purchase date) +- Overall: 30-day retention, users per household, expiration alert conversion + +--- + +## Next Actions + +1. **Approve roadmap** — User reviews ROADMAP.md and STATE.md +2. **Begin Phase 1 planning** — `/gsd:plan-phase 1` to decompose Phase 1 into executable plans +3. **Start Phase 1 implementation** — Implement AUTH-01-05 per plan details +4. **Validate Phase 1 completion** — All 5 success criteria demonstrated before Phase 2 starts + +--- + +## Session Context + +**This session:** +- Analyzed PROJECT.md, REQUIREMENTS.md, research/SUMMARY.md +- Derived 12-phase structure from 62 v1 requirements +- Created full ROADMAP.md with success criteria, dependencies, mapping +- Created STATE.md project tracking document +- Updated REQUIREMENTS.md traceability table + +**Tokens used:** ~24K (analysis + writing) + +**Files created/updated:** +- `.planning/ROADMAP.md` ✓ (12 phases, 62 requirements, 100% coverage) +- `.planning/STATE.md` ✓ (project state tracking) +- `.planning/REQUIREMENTS.md` ✓ (traceability table updated) + +--- + +*State document created: 2026-01-27* +*Roadmap approved for planning: No (awaiting user confirmation)*