Feature Spec: Contextual Notifications (Doc 08)

Product specification for expiry, shopping, quiet-hours, vacation, and final-call notification behavior.

1. User Goal

To receive timely, actionable, and non-intrusive "nudges" that prevent food waste and simplify household restocking without the user needing to manually check the app.

2. The Assistant’s Voice (Fixed Tone)

The assistant is not a robot; it is a helpful, slightly playful member of the household. * Tone: Casual, fun, and supportive. * Style: Uses "We" and "The [Item]" to maintain the shared-resource feeling. * Example: Instead of "Milk expires tomorrow," the assistant says: "The Milk is feeling a bit lonely. Let’s make sure we use it by tomorrow!"

3. Notification Logic & Triggers

A. The Combined "Snack & Expiry" Nudge

Time Window: Daily, 4:00 PM – 6:00 PM.
Logic: The app scans for items that meet two criteria:
1. Status: Already opened (needs finishing).
2. Urgency: Expiring within 48 hours.
Result: A single, consolidated notification.
Actionable Text: "Energy dip? The Digestive Biscuits are open and the Apple is ready to go! 🍎🍪"

B. The Escalating Weekend Shopping Nudge (Owner Only)

Trigger 1 (Saturday 09:00 AM): A summary of the "Used Up" list and items missing from the Monday-Sunday Menu.
- Text: "Ready for the Saturday shop? Here is what the house is missing for next week’s menu."
Trigger 2 (Sunday 09:00 AM - Optional): Only fires if the Owner did not interact with the Saturday notification or mark any items as "Bought."
- Text: "Happy Sunday! Just a quick check-in: we still need those staples before the Monday rush starts."

C. The "Final Call" Expiry Alerts

Trigger: 24 hours before any item’s hard expiry date.
Action: High priority.
Text: "Final call for the Spinach! 🥬 Use it tonight or it might get sad."

4. UI/UX: Notification Design (Android Specifics)

Action Buttons: Every notification should have at least one "Quick Action":
- Expiry Alert: [Mark as Used] | [Ignore]
- Weekend Nudge: [Open Shopping List]
Grouping: Multiple alerts from Homey must be "stacked" in the Android notification drawer to avoid cluttering the user’s screen.

5. Logic Rules & Safety

Scenario	System Response
Vacation Mode	All lifestyle and snack nudges are suppressed. Only "Final Call" alerts for high-value items are sent.
Night Mode	No notifications between 10:00 PM and 07:00 AM unless it’s a "Critical Alert" (customizable by user).
Already Eaten	If the Chef marks an item as "Used" 1 hour before the 4:00 PM snack window, the nudge for that item is cancelled.

Scenario

System Response

Vacation Mode

All lifestyle and snack nudges are suppressed. Only "Final Call" alerts for high-value items are sent.

Night Mode

No notifications between 10:00 PM and 07:00 AM unless it’s a "Critical Alert" (customizable by user).

Already Eaten

If the Chef marks an item as "Used" 1 hour before the 4:00 PM snack window, the nudge for that item is cancelled.

6. Data Model Requirements

notification_log: [ID, Type, Timestamp, WasClicked]
user_preferences: [UserID, QuietHoursStart, QuietHoursEnd, OptInSnackNudge(Bool)]