mystiatech/Sage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: create roadmap (12 phases)

Browse Source 
Phases:
1. Auth & Accounts
2. Household Creation
3. Barcode Scanning
4. Manual Entry & Search
5. Expiration Management
6. In-App Notifications
7. External Notifications (Discord, ntfy, Pushbullet, Telegram)
8. Usage Tracking
9. AI Shopping Prediction
10. Local Sales Tracking
11. Web App & Cross-Platform UI Polish
12. Setup Wizard & Onboarding

All 62 v1 requirements mapped to exactly one phase (100% coverage).
Critical path: 1→2→3→4→5→6→7
Parallel path: 4→8→9→10
Core value delivered after Phase 5 (expiration alerts).

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
Dani B
2026-01-27 23:50:49 -05:00
parent a9ff5e8607
commit 3e9a698bf2
3 changed files with 653 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
.planning/REQUIREMENTS.md
View File

@@ -148,84 +148,87 @@ Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status | | Requirement | Phase | Status |
|-------------|-------|--------| |-------------|-------|--------|
| INV-01 | — | Pending | | INV-01 | 3 | Pending |
| INV-02 | — | Pending | | INV-02 | 4 | Pending |
| INV-03 | — | Pending | | INV-03 | 4 | Pending |
| INV-04 | — | Pending | | INV-04 | 4 | Pending |
| INV-05 | — | Pending | | INV-05 | 4 | Pending |
| INV-06 | — | Pending | | INV-06 | 8 | Pending |
| INV-07 | — | Pending | | INV-07 | 8 | Pending |
| SHARE-01 | — | Pending | | SHARE-01 | 2 | Pending |
| SHARE-02 | — | Pending | | SHARE-02 | 2 | Pending |
| SHARE-03 | — | Pending | | SHARE-03 | 2 | Pending |
| SHARE-04 | — | Pending | | SHARE-04 | 2 | Pending |
| SHARE-05 | — | Pending | | SHARE-05 | 2 | Pending |
| SHARE-06 | — | Pending | | SHARE-06 | 4 | Pending |
| SHARE-07 | — | Pending | | SHARE-07 | 4 | Pending |
| SHARE-08 | — | Pending | | SHARE-08 | 4 | Pending |
| SHARE-09 | — | Pending | | SHARE-09 | 4 | Pending |
| SHARE-10 | — | Pending | | SHARE-10 | 11 | Pending |
| EXP-01 | — | Pending | | EXP-01 | 5 | Pending |
| EXP-02 | — | Pending | | EXP-02 | 5 | Pending |
| EXP-03 | — | Pending | | EXP-03 | 5 | Pending |
| EXP-04 | — | Pending | | EXP-04 | 5 | Pending |
| EXP-05 | — | Pending | | EXP-05 | 5 | Pending |
| EXP-06 | — | Pending | | EXP-06 | 5 | Pending |
| EXP-07 | — | Pending | | EXP-07 | 5 | Pending |
| AUTH-01 | — | Pending | | AUTH-01 | 1 | Pending |
| AUTH-02 | — | Pending | | AUTH-02 | 1 | Pending |
| AUTH-03 | — | Pending | | AUTH-03 | 1 | Pending |
| AUTH-04 | — | Pending | | AUTH-04 | 1 | Pending |
| AUTH-05 | — | Pending | | AUTH-05 | 1 | Pending |
| NOTF-01 | — | Pending | | NOTF-01 | 6 | Pending |
| NOTF-02 | — | Pending | | NOTF-02 | 7 | Pending |
| NOTF-03 | — | Pending | | NOTF-03 | 7 | Pending |
| NOTF-04 | — | Pending | | NOTF-04 | 7 | Pending |
| NOTF-05 | — | Pending | | NOTF-05 | 7 | Pending |
| NOTF-06 | — | Pending | | NOTF-06 | 7 | Pending |
| NOTF-07 | — | Pending | | NOTF-07 | 7 | Pending |
| AI-01 | — | Pending | | AI-01 | 8 | Pending |
| AI-02 | — | Pending | | AI-02 | 8 | Pending |
| AI-03 | — | Pending | | AI-03 | 8 | Pending |
| AI-04 | — | Pending | | AI-04 | 9 | Pending |
| AI-05 | — | Pending | | AI-05 | 9 | Pending |
| AI-06 | — | Pending | | AI-06 | 9 | Pending |
| AI-07 | — | Pending | | AI-07 | 9 | Pending |
| SALES-01 | — | Pending | | SALES-01 | 10 | Pending |
| SALES-02 | — | Pending | | SALES-02 | 10 | Pending |
| SALES-03 | — | Pending | | SALES-03 | 10 | Pending |
| SALES-04 | — | Pending | | SALES-04 | 10 | Pending |
| SALES-05 | — | Pending | | SALES-05 | 10 | Pending |
| SALES-06 | — | Pending | | SALES-06 | 10 | Pending |
| SALES-07 | — | Pending | | SALES-07 | 10 | Pending |
| SETUP-01 | — | Pending | | SETUP-01 | 12 | Pending |
| SETUP-02 | — | Pending | | SETUP-02 | 12 | Pending |
| SETUP-03 | — | Pending | | SETUP-03 | 12 | Pending |
| SETUP-04 | — | Pending | | SETUP-04 | 12 | Pending |
| SETUP-05 | — | Pending | | SETUP-05 | 12 | Pending |
| SETUP-06 | — | Pending | | SETUP-06 | 12 | Pending |
| UI-01 | — | Pending | | UI-01 | 11 | Pending |
| UI-02 | — | Pending | | UI-02 | 11 | Pending |
| UI-03 | — | Pending | | UI-03 | 11 | Pending |
| UI-04 | — | Pending | | UI-04 | 11 | Pending |
| UI-05 | — | Pending | | UI-05 | 11 | Pending |
| UI-06 | — | Pending | | UI-06 | 11 | Pending |
| UI-07 | — | Pending | | UI-07 | 3 | Pending |
| DATA-01 | — | Pending | | DATA-01 | 3 | Pending |
| DATA-02 | — | Pending | | DATA-02 | 11 | Pending |
| DATA-03 | — | Pending | | DATA-03 | 11 | Pending |
| DATA-04 | — | Pending | | DATA-04 | 11 | Pending |
| DATA-05 | — | Pending | | DATA-05 | 11 | Pending |
| DATA-06 | — | Pending | | DATA-06 | 12 | Pending |
| DATA-07 | — | Pending | | DATA-07 | 12 | Pending |
| DATA-08 | — | Pending | | DATA-08 | 12 | Pending |
| DATA-09 | — | Pending | | DATA-09 | 12 | Pending |
**Coverage:** **Coverage:**
- v1 requirements: 62 total - v1 requirements: 62 total
- Mapped to phases: 0 - Mapped to phases: 62
- Unmapped: 62 ⚠️ (will be filled by roadmap) - Unmapped: 0 ✓
- **Coverage: 100%**
--- ---
*Requirements defined: 2026-01-27* *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*

355
.planning/ROADMAP.md Normal file
View File

@@ -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*

220
.planning/STATE.md Normal file
View File

@@ -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)*