Recipe Improvement

Database: meal-planner. Progress file: data/recipe_review_progress.json.

Enhancement Data Safety

Enhanced recipes store both versions in the same Firestore document:

• Top-level fields = enhanced version (app displays these)
• original nested field = immutable snapshot of scraped data (set once on first enhancement)
• enhanced: true flag, enhanced_at (ISO 8601 UTC), changes_made (list of strings, same language as recipe)

Rules

1. NEVER use .set() — destroys fields not in payload. Always .update() to merge
2. original is immutable — set once on first enhancement, never modified
3. Always fetch before modifying — recipe_manager.py get <id>
4. update command handles snapshotting — creates original on first enhancement, preserves existing on re-enhancement

Common mistakes

Update JSON format — only include changed fields:

{ "ingredients": ["..."], "instructions": ["..."], "cuisine": "Swedish", "tags": ["vegetarian"] }

PowerShell: Write complex JSON to a temp file first, then pass with (Get-Content data/temp_update.json -Raw).

Configuration Files

Read BOTH before making any recommendations:

1. household-config.md (this directory): Dietary preferences, household size, serving target, pantry staples
2. equipment.md (this directory): Available cooking equipment, temperatures, cooking times

Improvement Principles

1. Timing and Staggering

2. Component-Level Equipment Optimization

Evaluate each component independently — don't treat equipment as all-or-nothing.

Check equipment.md for specific temperatures/times. Only suggest airfryer when it genuinely improves the dish.

3. Vegetarian Protein Adaptations

When household-config.md specifies vegetarian alternatives:

1. Read preparation notes in household-config.md for the specific protein type
2. Update oil quantities — soy mince needs extra oil (less fat than meat)
3. Adjust cooking times — don't just swap the ingredient name
4. Add tips where behavior differs (e.g., "browns faster", "add liquid if dry")
5. Remove meat-specific language from instructions ("kött", "köttfärs")

4. Flavor Enhancements

Use pantry staples from household-config.md:

• Roasted proteins from airfryer: Finish with butter, citrus, fresh herbs
• Roasted vegetables: Quality oil + flaky salt before serving
• Grains: Stir in butter/oil for richness
• Sauces: Brighten with citrus at the end

5. Practical Adjustments

• Never consolidate ingredients — if listed multiple times, trust there's a reason (different phases/purposes)
• Clarify vague quantities: "salt och peppar" → "1/2 tsk salt, 2 krm svartpeppar"
• Suggest mise en place order

6. Measurements

Volumetric with weight (non-spice dry goods): "2 dl Ris (160 g)", "1 dl Mjöl (60 g)". Exclude spices and liquids (1 liter ≈ 1 kg, so weight adds no value).

Round to measurable units:

Prefer: krm < tsk < msk over ml for small amounts.

7. HelloFresh Portion Markers

[X | Y] = 2P | 4P. [X, 2P] = value for 2 portions. Always use 4P value. Remove all markers from output.

Verification Checklist

Before finalizing any improvement, verify ALL of these:

1. No fractions < ½ tsk — use krm instead (❌ ¼ tsk → ✅ 1 krm)
2. Ingredient accounting — every ingredient in the list appears in instructions, none omitted or moved without justification
3. Ingredient order — listed in the order they are first used in the instructions (spices always last)
4. Original intent preserved — which items are cooked vs raw, combined vs separate, intended texture
5. Dairy identity preserved — never substitute dairy types (syrad grädde ≠ grädde, gräddfil ≠ crème fraîche). Only add "(laktosfri)" suffix
6. Timing sanity — total cooking time makes sense after staggering
7. Cross-reference — trace each ingredient: list → instructions → final dish

Instruction Formatting

Tips use 💡 prefix as separate array entries after the step they relate to:

["Skala pumpan och skär i bitar.",
 "💡 ALTERNATIV: Använd hokkaidopumpa - skalet är ätbart.",
 "⏱️ 5 min: Ställ in i ugnen..."]

• ❌ Embedded in step text: "Skala pumpan... 💡 ALTERNATIV: ..."
• ✅ Own entry starting with 💡 — mobile app renders with distinct green styling
• Tips field is for reference info (spice composition, storage notes) — NOT substitutions or technique alternatives

Timeline format for parallel cooking: ⏱️ X min: prefix. Only when timing coordination matters.

Output Format

1. Summary of changes: What you're improving and why
2. Verification notes: Confirm ingredient accounting
3. Updated ingredients: Only if changes needed
4. Updated instructions: Full rewritten instructions
5. Tips: Optional cooking tips

Anti-Patterns

Language

• Keep recipes in Swedish (matching source)
• Swedish cooking terminology and metric measurements (g, ml, dl, msk, tsk)
• Avoid generic terms like "protein" — use actual ingredient names

Prompt System

Modular prompt files in config/prompts/:

config/prompts/
  core/          # Committed — applies to ALL users
    base.md      # Role, output JSON schema
    formatting.md # Fractions, ingredient order, Swedish measurements
    rules.md     # Forbidden terms, HelloFresh spice replacements
  user/          # User-specific preferences
    dietary.md   # Dietary restrictions, protein substitutions
    equipment.md # Kitchen equipment specs

Load via api/services/prompt_loader.py:

from api.services.prompt_loader import load_system_prompt, validate_prompts
prompt = load_system_prompt()      # Complete prompt (core + user)
status = validate_prompts()        # Dict of file -> exists

Key Rules Enforced in Prompts

• Forbidden terms: "protein/proteiner" → use specific names
• No consolidation: Keep separate ingredient entries
• Concrete quantities: "1 paket" → "400 g", "en nypa" → "2 krm"
• Swedish fractions: ½, ⅓, ¼ — never 0.5, 0.33
• HelloFresh spices: Replace blends with individual spices