3e9a698bf2
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>
8.4 KiB
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):
- Phase 1 (Auth) must complete before any feature phases can start
- Phase 2 (Households) must complete before Phase 3 (inventory sync requires household context)
- Phase 3 (Barcode) must complete before Phase 4 (search/filtering refinement)
- Phase 4 (Manual Entry) must complete before Phase 5 (expiration depends on items existing)
- 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
- Approve roadmap — User reviews ROADMAP.md and STATE.md
- Begin Phase 1 planning —
/gsd:plan-phase 1to decompose Phase 1 into executable plans - Start Phase 1 implementation — Implement AUTH-01-05 per plan details
- 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)