Meal Plan

/meal-plan — Weekly Meal Planner

Generate an optimized weekly meal plan with an aisle-grouped shopping list.

Announce at start:

Generating weekly meal plan...

Options (all optional):
  • meal count:     "/meal-plan 4 meals"
  • skip protein:   "/meal-plan skip salmon"
  • force-include:  "/meal-plan include lemon-garlic chicken"
  • combine freely: "/meal-plan 4 meals skip chicken"

Step 1: Parse User Constraints

The user may provide optional constraints along with the command:

• Skip ingredient/protein: "skip salmon", "no shrimp this week" → exclude recipes with that protein
• Meal count: "only 4 meals", "plan 3 meals" → change from default of 5
• Force-include: "include lemon-garlic chicken" → force a specific recipe into the plan
• Other: any other preferences stated by the user

If no constraints are given, use defaults: 5 meals, no exclusions.

Step 2: Read All Inputs

Read these files in parallel:

2a. Recipes

Read all data/recipes/*.md files using Glob to find them, then Read each one.

For each recipe, parse the YAML frontmatter to extract:

• name
• protein
• canonical_ingredients (list)
• rating (may be blank)
• total_time
• tags

If 0 recipes exist: Stop and tell the user: "No recipes found in data/recipes/. Run /meal-add to add recipes first."

If 1-4 recipes exist: Proceed but note: "Only N recipes in rotation — plan will include all available meals."

2b. Flyers

Read data/flyers/*.md files. Use the filename date to determine recency.

Current flyers: files with a date within the last 7 days (based on today's date vs. filename date YYYY-MM-DD).

• If current flyers exist for both stores, use both
• If only one store has a current flyer, use it
• If no current flyers exist, warn: "No current flyer data found (last flyer is from [date]). Proceeding without sale prices — on-sale bonuses will not apply."

For each current flyer, parse:

• The "Core Ingredients On Sale This Week" section to get canonical IDs and prices
• The full sale items table for price reference
• The "Likely Loss Leaders" section to get canonical IDs flagged as loss leaders (these get a higher scoring bonus than regular on-sale items)

2c. Recent Plans

Read the most recent data/meal-plans/*.md file (by filename date — use the single most recent file regardless of age).

Extract the list of meal names from the "Selected Meals" section. These meals get a repetition penalty.

If the most recent plan is older than 7 days, still apply the penalty but add a note in the Warnings section: "Repetition penalty applied from a plan dated [date] — may be stale."

If no plan files exist at all, no repetition penalty applies.

2d. Household Config

Read data/config.yaml for:

• stores list (for flyer matching and sale annotations)
• excluded_ingredients (filter recipes before scoring)
• ingredient_thresholds (for shopping list count checks)
• rotation_target (for rotation tightness warnings)

If the file does not exist: Stop and tell the user: "data/config.yaml is missing. Run /meal-setup first to initialize the project, then re-run /meal-plan."

2e. Canonical Ingredients

Read data/canonical-ingredients.yaml for:

• Aisle mappings (for shopping list grouping)
• Pantry staple flags (for ingredient count thresholds)

If the file does not exist: Stop and tell the user: "data/canonical-ingredients.yaml is missing. Run /meal-setup first to initialize the project, then re-run /meal-plan."

2f. Price History

Read data/receipts/price-history.yaml if it exists.

For each canonical ingredient, compute the average price from all ledger entries. Use these averages to estimate recipe costs when no cost data exists in the recipe's Ratings section.

If the file doesn't exist, skip — cost estimates will only use recipe Ratings data (if any).

Step 3: Score Recipes

Apply the scoring formula to each recipe. Use these explicit weights:

Individual Recipe Score (computed first)

Individual score = family_rating + (on_sale_bonus * count_of_on_sale_only_ingredients) + (loss_leader_bonus * count_of_loss_leader_ingredients) - cost_penalty - repetition_penalty

Combination Scoring (computed second)

1. Sort all eligible recipes by individual score (descending)
2. Cap at the top 8 candidates — never enumerate combinations from a larger pool. This keeps the combination count manageable regardless of rotation size.
3. For combinations of [meal_count] meals from this pool of 8, compute:

Ingredient overlap bonus: +0.5 for each canonical ingredient that appears in 2 or more of the selected meals. This rewards meal combinations that share ingredients, reducing the shopping list.

Prep burden constraint: If more than 2 of the selected meals are high-effort (>45 min), apply -1.0 penalty per additional high-effort meal beyond the 2nd.

4. Final combination score = sum(individual scores) + overlap_bonus - prep_excess_penalty
5. Pick the highest-scoring combination

If the recipe pool is small (fewer than [meal_count] + 2 candidates): Skip combination enumeration. Just use the top [meal_count] recipes by individual score and note in the plan that overlap scoring was not applied.

Applying User Constraints

• Skip protein: Remove all recipes with that protein value before scoring
• Force-include: Add the specified recipe to the plan, then fill remaining slots by score from the pool
• Meal count: Adjust combination size accordingly

Step 4: Preview and Confirm

Show the proposed plan before writing any files:

Proposed meal plan — Week of YYYY-MM-DD

  Meals (N):
  1. [Recipe Name]  [score: X.X]  [⏱ XX min]  [⚠ non-mediterranean if flagged]
     On-sale ingredients: [canonical_id — $X.XX @ Store, ...]  or  none
     Loss leader ingredients: [canonical_id — $X.XX @ Store, ...]  or  none
  2. [Recipe Name]  ...
  3. ...

  Shared ingredients: [N] — [list of canonical IDs shared by 2+ meals]
  On-sale matches: [N] ingredients from these meals are on sale this week

  Constraints applied: [e.g. "5 meals, no exclusions" or "skipped salmon"]
  Flyer used: [store name, date range]  or  "none (no current flyer)"

Confirm this plan? (yes / swap [#] for [recipe name] / change to [N] meals / cancel)

Swap handling: If the user says "swap 2 for Rosemary Chicken", replace that slot with the named recipe (or the next highest-scoring eligible recipe if no name is given), re-check overlap, re-show the preview.

Cancel: Stop — do not write any files.

Yes: Continue to Step 5.

Step 5: Write Meal Plan File

Ensure directories exist: run mkdir -p data/meal-plans data/shopping-lists via Bash before writing.

Write to data/meal-plans/YYYY-MM-DD-plan.md (using today's date):

---
date: YYYY-MM-DD
meals: [number]
store_flyers:
  - [flyer-filename-without-extension]
---

# Meal Plan — Week of YYYY-MM-DD

## Selected Meals

### 1. [Recipe Name]
- **Why picked:** [Explain: rating, on-sale ingredients, overlap with other meals, any bonuses]
- **Estimated cost:** ~$[estimate]

### 2. [Recipe Name]
- **Why picked:** [reasoning]
- **Estimated cost:** ~$[estimate]

[...repeat for each meal]

## Ingredient Overlap

| Ingredient | Used In |
|-----------|---------|
| [canonical_id] | Meals [list] |

**Shared ingredients:** [N] ingredients appear in 2+ meals

## Cost Summary

- **Estimated total:** ~$[total] *(rough estimate — based on recipe ratings data if available, otherwise omitted)*
- **On-sale savings:** [note any sale items used]

## Warnings

[Any warnings: stale flyer, unrated meals, tight rotation, ingredient count issues]

## Unrated Meals to Review After This Week

- [ ] [Recipe Name] → edit data/recipes/[slug].md

Warning conditions to check:

• Flyer data is stale or missing
• Any selected meals are unrated (remind user to fill in ratings after cooking)
• Rotation is tight (fewer than 8 recipes total in data/recipes/)
• Ingredient count exceeds threshold (check after generating shopping list)
• Cost estimates are rough — only include them when a recipe's Ratings section has an actual cost entry. If no cost data exists for a meal, omit the estimate rather than guessing. Add a note in the Warnings section: "Cost estimates incomplete — fill in recipe ratings after cooking."

Step 6: Generate Shopping List

Write to data/shopping-lists/YYYY-MM-DD-list.md (using today's date):

Building the list

For each selected meal's recipe:

1. Read the full ## Ingredients section
2. For each ingredient, look up the canonical ID
3. Sum quantities across meals where the same canonical ingredient appears — but only when units are compatible:
   • Same unit: sum directly ("1 lb" + "1.5 lb" = "2.5 lb", "2 cloves" + "3 cloves" = "5 cloves")
   • Convertible units: convert to a common unit before summing ("1 cup" + "2 tbsp" → convert to tbsp: 16 + 2 = 18 tbsp ≈ "1 cup + 2 tbsp")
   • Incompatible units: list separately with a note ("3 cloves garlic + 2 tbsp minced garlic → list as '3 cloves + 2 tbsp (from 2 recipes)'")
   • No quantity stated (e.g., "salt to taste", "olive oil for drizzling"): list once, note "from [N] recipes"
4. Look up the aisle from canonical-ingredients.yaml
5. Check if the ingredient is a pantry staple

Aisle groups (in this order):

1. Produce
2. Meat & Seafood
3. Dairy & Eggs
4. Canned & Dry Goods
5. Grains & Pasta
6. Pantry (oils, spices, etc.)

Shopping list format:

---
date: YYYY-MM-DD
plan: YYYY-MM-DD-plan
total_estimated_cost: $[total]
unique_ingredients: [count excluding pantry staples]
---

# Shopping List — Week of YYYY-MM-DD

## [Aisle Name]
| Item | Qty | Est. Price | Used In | Sale? |
|------|-----|-----------|---------|-------|
| [Display name] | [summed qty] | $[est.] | [Meal numbers] | [**$X.XX @ Store** if on sale] |

[...repeat for each aisle group]

## Likely On Hand (Pantry Staples)
| Item | Used In |
|------|---------|
| [Display name] | [Meal numbers] |

---

**Total estimated cost:** ~$[total] (excluding pantry staples)
**Unique ingredients to buy:** [count]
**Ingredient budget:** [count]/[target from config] target — [on track / warning / over budget]

Ingredient count check:

Read ingredient_thresholds from data/config.yaml:

• Count unique non-pantry-staple ingredients
• If ≤ target: "on track"
• If between target + 1 and warning - 1: no comment needed
• If between warning and too_complex - 1: display warning "Above target — consider simplifying"
• If ≥ too_complex: display strong warning "Well over budget — this plan may be too complex"

Sale annotations:

• For each ingredient on sale in a current flyer, bold the price and store name
• If on sale at both stores, show the cheaper one: "$X.XX/unit @ [Store A] (also $Y.YY/unit @ [Store B])"

Step 7: Confirm

Output a summary:

Meal plan generated!

  Plan: data/meal-plans/YYYY-MM-DD-plan.md
  Shopping list: data/shopping-lists/YYYY-MM-DD-list.md

  This week's meals:
  1. [Meal name] — ~$[cost]
  2. [Meal name] — ~$[cost]
  3. [Meal name] — ~$[cost]
  4. [Meal name] — ~$[cost]
  5. [Meal name] — ~$[cost]

  Estimated total: ~$[total]
  Ingredients to buy: [N] (target: ≤[target from config])
  Shared ingredients: [N] appear in 2+ meals
  On-sale items used: [N]

  [Any warnings]

  After cooking this week, remember to update ratings in the recipe files!