Recipe Validation

Validation Checklist

Go through every category below, one item at a time. Do not skip categories. Do not say "looks good" without checking each item. Fix what you can. Flag what you cannot.

1. File and Structure

• File extension is .yaml
• File is valid YAML (no syntax errors)
• name is present and descriptive
• version is present and quoted ("1.0" not 1.0)
• author is present
• description is present and not empty
• status is one of: stable, beta, draft
• File is in the correct folder for its status
• Filename is Title_Case_With_Underscores.yaml

2. Ingredients

• At least one ingredient group with at least one item
• Every ingredient has quantity and unit
• Units are ONLY g, ml, or count words (cloves, sprigs, whole)
• No imperial units (lbs., cups, oz.) — if found, convert to grams
• Every spice with quantity < 10 and unit: g has a volume_alt field
• heading: null for the default group, descriptive string for sub-groups

3. Instructions

• At least one instruction section (unless status: draft)
• Steps are in a logical, executable order
• Every section has type: sequence or type: branch
• Branch sections with the same cooking choice share a branch_group
• Each branch is complete on its own (no branch depends on steps from another)
• All temperatures are dual-format: °C (°F)
• No step references an ingredient not in the ingredients list
• Every step is explicit enough for a novice — no implicit actions assumed (R3.7)

4. Food Safety

These are ALWAYS errors if missing. Never skip this section for meat recipes.

• Poultry → internal temp of 74°C (165°F) stated in instructions
• Ground meats → internal temp of 71°C (160°F) stated
• Whole cuts (beef/pork/lamb) → internal temp of 63°C (145°F) stated
• Past-expiration ingredient advice includes a safety caveat
• Freezing instructions include maximum storage duration
• Flash-freeze steps describe the process (spacing, timing, transfer)

5. Cross-References

• All path values in related[] point to files that exist
• Paths use relative format (./ or ../)
• Paths end in .yaml, not .md
• Every ingredient whose name refers to another recipe in this repo has a doc_link field with the relative path to that recipe's .yaml file
• If a recipe was moved or renamed, all references to the old path across the repo have been updated

6. Text Quality

• No merged/concatenated words from copy-paste (e.g. "Fahrenheittested") — scan all pasted text
• No placeholder text (TBD, TODO) in stable or beta recipes
• Ingredient names are spelled correctly
• Step text is clear and unambiguous

7. Consistency

• Units are consistent throughout (no mixing g and oz for same ingredient type)
• Same ingredient uses the same name everywhere in the file
• notes field only present when status is beta or draft
• No imperial units in text fields (description, step text, ingredient notes, top-level notes) — check for lb, oz, cup, tbsp, tsp, °F alone — any found must be converted or removed
• All nutrition_id values reference actual entries in docs/data/nutrition-db.json — if a recipe introduces new ingredients, the DB entries must be added in the same PR
  • If docs/data/nutrition-db.json was changed in this PR, run dotnet build and confirm the wwwroot copy is generated at visualizer/src/OpenCookbook.Web/wwwroot/data/nutrition-db.json (and is not tracked in git)

How to Report Issues

For things you fixed:

[FIXED] Missing volume_alt on 3g Black Pepper — added "3/4 tsp."
[FIXED] Temperature "425°F" → "218°C (425°F)"

For things only the author can decide:

[ASK] Ground beef listed as 907g — is this the intended amount? (Converted from 2 lbs)
[ASK] Chicken Wings spice quantities may need halving — needs testing to confirm.

Promoting Beta → Stable

A recipe can move from Recipes/Beta/ to Recipes/ when ALL of these are true:

1. Every checklist item above passes
2. No open [ASK] items remain
3. The notes field is removed or empty
4. All quantities have been tested by the author
5. status is changed from beta to stable

Improving the Rules

This section is not optional. If your validation pass reveals a gap, fix the system — not just the recipe.

1. Add a rule to RULES.md if the error class isn't covered
2. If a spice was missing, add it to SPICE_CONVERSIONS.md
3. Add a checklist item above if it catches a new class of error
4. Log the discovery in lessons.md with a prevention rule

If the same type of mistake keeps appearing, the system is broken — fix the system.