Product Tools · Lead MVP
Weekly Groceries.
Plan your week's groceries in three taps — pick a store, build a plan, share it with your household. The chore everyone already does, made repeatable, shared, and quietly cheaper.
Live · auto-refreshed on every push + daily
Updated: May 16, 2026
Sources: git · CHANGES.md · canonical screens · Figma
Key Insights · Read this first
What it is
A 3-step weekly grocery planner: address → store → plan, then share with your household.
Why it matters
The highest-frequency household chore — done every week. The easiest way to make Geez a daily habit.
Where it stands
All 4 screens designed and built. Now wiring to live data + getting it on a phone.
The next step
Clean build on Gene's phone, then the orchestrator + real services.
★ The Experience
Four screens. Each ask is a gift exchange.
Every data ask explains why we need it, what it unlocks now, and what it means long-term. Data gathering should feel like a gift exchange, not a form. Personal until shared — then the household layer activates.
1
Home Address
The trust-building ask, with a real preview of the experience — so the address feels earned, not extracted.
SET · address entry
2
Pick Your Store
Three closest stores, best-match pre-selected. Ranked by the decision engine + your history. A favorite seeds loyalty + savings.
CONFIRM · store choice
3
Weekly Plan
7 days, each with a meal-type icon (home / takeout / out). Staples, dynamic pricing, preferred store auto-selected.
TRACK · day grid
↗
Share with Household
Guest (view-only) vs household (view + edit). Family upgrade offered naturally — kids 15 & under always free.
CONFIRM · useRSVP
★ What It Must Do
Requirements. Invariants, not preferences.
The non-negotiables — grounded in product law. If a build breaks one of these, it isn't shippable.
✓
Group dimension
No tool is solo — WG is the household layer; the share step is structural. Group law
✓
New-user-first
Starts at Step 1 until the first plan is saved; never assumes a returning state.
✓
Household vs guest access
Guests view-only until subscribed; household members edit. ADR-025
✓
Kids always free
15 & under never gate on subscription. ADR-026
✓
Magic Curve motion
936ms · cubic-bezier(0.16,1,0.3,1), 350ms stagger on entrances. UI Rule 4
✓
Tokens & Figma truth
Every value via useTokens(); every screen cites its Figma node — fidelity over invention.
✓
Orchestrator pattern
5+ services compose through useWeeklyGroceriesFlow, never flat in the screen. Path B
✓
Repeatability
Recurrence drives weekly plans + dollar/time savings tracking. ADR-021
★ Why It Matters
The wedge. Highest frequency. Shared by definition.
Weekly Groceries is the lead tool because it's the highest-frequency household chore — repeated weekly, shared by default. It's where the relationship graph and the recurrence engine first earn trust, before higher-stakes tools.
Frequency hook
Recurs every week — earns the daily-open habit before anything else.
Acquisition engine
The share step turns one member into a household — a built-in viral loop.
Data flywheel
Store choice → loyalty depth → savings. Each week sharpens the ranking.
Composition proof
Validates the orchestrator architecture every future tool inherits.
Felt savings
Dollar + time tracking makes the subscription self-justifying.
Supply chain
Feeds Dinner Decider + Group Get Together — context reused, not re-asked.
The Thesis
Groceries are the chore everyone already does. Geez makes them repeatable, shared, and quietly cheaper — the first proof that the loom moves while you move.
Status — At a Glance
Where it stands. Design ahead, data catching up.
Composition
Build Phase
flat-wired → orchestrator
4 / 4
Screens Built
Address · Store · Plan · Share
2 / 5+
Services Wired
stubbed in canonical
wp-flows.1
Next Lane
orchestrator · unblocked
Building
On Device
EAS preview · SDK 54
Canary
Arch Role
first 5+ service tool
The one-liner for Dan
The full 1-2-3 flow exists and is designed. The work now is plumbing, not pixels: extract the screen logic into an orchestrator, swap the two stubbed hooks for real services, and land a clean build on Gene's phone.
Build Items
Work packages. Tracked against the queue.
| WP / Item | Scope | Status | Notes |
|---|
| wp-flows.1 | useWeeklyGroceriesFlow orchestrator | Next lane | Unblocked — async migration complete. |
| useRSVP wiring | Share screen → real RSVP service | Stubbed | Stub added in canonical to unblock build. |
| usePreferences wiring | Store ranking → preference history | Stubbed | getRecord / modeState / confirm stubbed. |
| Decision engine | new-vs-established rankOptions | Stubbed | Full engine in monorepo history (ce17ea1). |
| wp-grocery.recover.2/.3 | Recover polished flow from sibling branch | Gene eyeball | Path C Step 1 pending. |
| EAS preview build | On-device shell, SDK 54 | In flight | Dep alignment → rebuild. |
| Address autocomplete | Google Places, debounced, lat/lng | Built | Atom shipped (799bcfb). |
Decisions Log
How we got here. Newest first.
| Orchestrator (Path B) | WG is the canary: flat-wiring stops scaling at 5+ services. wp-flows.1 extracts first. |
| Async migration | Universal-service layer is now async-shaped. Unblocked wp-flows.1 + wp-vault.1. |
| Source of Truth Lock | Canonical screen paths SHA-locked after the polished WG flow was overwritten by a rebuild. |
| ce17ea1 | usePreferences + decision engine wired into Store screen — ranking by history + proximity + price. |
| 7bb619b | useRSVP wired into Share screen — first real use; household vs guest model. |
| e0521d4 | Steps 2 + 4 wired to real data — full flow complete with dynamic pricing. |
The Build — Screens
Screens. SHA-locked, canonical.
Canonical files live in ~/Developer/geez/src/components/screens/, each SHA-locked per the Source of Truth Lock. Figma node IDs to be backfilled.
| Screen | Role | Carrier / Archetype | Figma |
|---|
| WeeklyGroceriesScreen | Step 1 — Home Address | SET (form) | backfill |
| WeeklyGroceriesStoreScreen | Step 2 — Pick Store | CONFIRM (sectioned list) | backfill |
| WeeklyGroceriesListScreen | Step 3 — Weekly Plan | TRACK (day grid) | backfill |
| WeeklyGroceriesShareScreen | Share — household / guest | CONFIRM (sectioned list) | backfill |
Research & Foundations
What we know.
| Data Minimalism | Repeatability reduces build burden; reuse is a success metric. WG context feeds other tools. |
| Every Tool Has a Group | No tool is solo. WG is the household layer — the share step is structural. |
| New User First | Always start the new-user flow unless authenticated + subscribed. |
| Home Base Interconnection | Supply-chain flow; WG output is upstream input for meal & event tools. |
| Relationship Graph Seed | Phone contacts bootstrap relationships; share step is the first production exercise. |
| Earned Tool Unlock | Tools unlock through accomplishment (3 completions). WG is the on-ramp. |
Next Actions
To-dos. Ordered by what unblocks the most.
| # | Action | Owner | Unblocks |
|---|
| 1 | Align deps to SDK 54 → clean EAS preview build on Gene's phone | Build | On-device demo of full flow |
| 2 | Build useWeeklyGroceriesFlow orchestrator (wp-flows.1) | Core | Pattern for all future tools |
| 3 | Swap stubbed useRSVP / usePreferences for real services | Core | Real share + store ranking |
| 4 | Restore full ranking engine into canonical | Core | Intelligent store recommendation |
| 5 | Backfill Figma node IDs in all 4 screen headers | Design | Source-of-truth compliance |
| 6 | Resolve wp-grocery.recover.2/.3 (Gene eyeball) | Gene | Recovers lost polished flow |
Open Questions
Considerations & risks.
| Two-repo drift | Canonical vs monorepo. Real WG logic lives partly in monorepo history; canonical has stubs. |
| Stub debt | Three stubs mask real behavior to keep the build green. Demos show stub data until swapped. |
| Figma backfill | Screens predate the Figma Source Law; node IDs must be added. |
| EAS budget | 15 iOS builds/month. Shift to OTA updates for JS-only changes. |
| Pricing copy | $1/wk or $50/$100 annual; ensure Share family-upgrade copy matches. |
| Recurrence depth | Savings tracking designed but not yet wired into the List screen. |
Opportunity Radar
Continuously prioritized. Reach × frequency × leverage ÷ effort.
New opportunities are appended with a priority score (0–100). Gene accepts or defers — accepted/deferred items move, they're never dropped.
88Score
Savings ticker on the Plan screen
Surface week-over-week dollar + time saved right where the plan is confirmed. Turns a chore into a visible win. Engine exists, needs a surface.
82Score
One-tap re-run last week's plan
Returning users see last week as a delta, not a blank slate — accept-all in one tap. Highest-leverage retention move.
74Score
Household item assignment ("who shops what")
In a shared plan, assign items/aisles to members. Deepens the group dimension; exercises the relationship graph daily.
61Score
Loyalty-card mesh via useAccountMesh
Connect store loyalty accounts to auto-apply savings. High value, higher effort. Hold until wp-mesh stabilizes.
See It
Demos.
| EAS Preview Build | On-device iOS build (ad-hoc). Status: in flight — SDK 54 dep alignment. expo.dev → builds → |
| Web fallback | GeezSuperApp web build deployed as Layer-4 fallback. |
| Screen recordings | Flow walkthroughs — captured once the clean build lands on the phone. pending build |
