# Feature Specification: 001-pantry-meal-planner

*Created: 2026-08-18*

> Original request: pantry meal planner

## User Stories

### Story 1 — (P1)

As a home cook, I want to record what is in my pantry, so that meal suggestions
are based on what I actually have.

**Acceptance:** Given an empty pantry list, when I add "500 g rice" and
"2 cans tomatoes", then the pantry shows both items with their quantities.

### Story 2 — (P1)

As a home cook, I want a weekly plan of meals cookable from my pantry, so that
I don't have to decide every evening.

**Acceptance:** Given a pantry with rice, tomatoes and lentils, when I request
a plan for 7 days, then every suggested meal uses only pantry items and no
item is over-consumed across the week.

### Story 3 — (P2)

As a home cook, I want a shopping list for the gaps, so that one store visit
covers the whole week.

**Acceptance:** Given a 7-day plan that needs 3 onions while the pantry has 1,
when I open the shopping list, then it shows "2 onions" and nothing already
covered by the pantry.

## Requirements

- R1: The system must store pantry items as name + quantity + unit and support
  add, update and remove.
- R2: The system must generate a 7-day plan where each meal's ingredients are
  fully covered by the current pantry stock minus what earlier meals in the
  same plan consume.
- R3: The system must derive a shopping list as the difference between a plan's
  total ingredient needs and current stock.
- R4: Recipes come from a local, user-editable recipe file; a starter set of
  10 common recipes is bundled so the planner works out of the box.

**Entities:** PantryItem (name, quantity, unit), Recipe (name, ingredients),
MealPlan (7 ordered days -> recipe), ShoppingList (derived).

## Success Criteria

- S1: Recording a 10-item pantry takes under 2 minutes.
- S2: A generated 7-day plan never references an ingredient with insufficient
  stock at the point it is cooked.
- S3: Buying exactly the shopping list makes every meal of the week cookable.

## Assumptions

- A1: Single household, single device, no sharing — fully local data.
- A2: Quantities use metric units and piece counts; no unit conversion in v1.
- A3: One meal per day is planned (dinner); breakfast/lunch out of scope.