docs(meal-planning): document one-document-per-variant recipe pattern

[St0nefish]

Summary

Documents a recipe-authoring pattern for the add-recipe skill that was already established in practice in the household knowledge base, but never written down: a recipe with two or more genuinely different ways to cook it (different equipment, different cut, different timings) gets one document per variant, not one document with the alternates folded into prose.

This is catching the skill up to the corpus, not proposing something new — the KB has already been migrated to this pattern.

Why

Two concrete failure modes were found in the live knowledge base under the old single-document approach:

1. Ingredients silently missing from the cart. grocery-cart reads shopping lines only from inside the fenced ```text block. One recipe put its second method's protein in a prose sentence after the fence ("For Method B only, add chicken thighs — bone-in | 1 | pack | required") so that protein was never carted. Two more recipes had the same shape — a beer alternative whose beer was never listed, and a boneless variant whose protein wasn't either.
2. The planning block can only describe one method. planning holds a single method, effort, and cook_minutes — exactly what the planner schedules and orders a cycle on. A recipe spanning a 20-minute stovetop version and an 8-hour slow-cooker version was lying about one of them; the variants are different schedulable objects, not variations of one.

What changed

• Added a "Recipes with more than one method" section to plugins-claude/meal-planning/skills/add-recipe/SKILL.md, placed after "Retrofit mode" and before "What to report at the end" (alongside the other end-of-file special-case sections). Covers: one document per variant, when a shared-components document is worth extracting (and when it isn't), cross-linking variants, substitutions vs. variants, handling tested/rating and path stability when splitting an existing recipe, and the expected near-duplicate-write refusal when authoring a second variant.
• Added one sentence to the step 5 shopping-list guidance making explicit that every shopping line must live inside the fenced block, since a prose line is invisible to grocery-cart — with a pointer down to the new section.

Only plugins-claude/meal-planning/skills/add-recipe/SKILL.md is touched.

Validation

• .github/scripts/validate-frontmatter.sh — 103 checks, 0 failures
• .github/scripts/validate-plugins.sh — 301 checks, 0 failures
• rumdl check on the changed file — no issues
• Full bash test.sh suite — 1857 passed, 1 failed. The one failure is tests/freecad/test-model.sh (No module named 'wwkit'), a pre-existing environment gap unrelated to the meal-planning plugin — confirmed by re-running that suite in isolation.

Note

This repo's auto-merge.yml enables auto-merge on PR open, so this may merge itself once CI passes — that's expected repo automation, not a manual action.

[Copilot]

🟡 Changes recommended

Two new doc statements inaccurately imply grocery-cart parses recipe fences directly, which conflicts with the documented flow where grocery-cart reads shopping lines from the active plan.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Documents the “one document per variant” pattern for recipes that have genuinely different cooking methods, clarifying how planning metadata and shopping-list extraction behave in the meal-planning knowledge base workflow.

Changes:

• Adds an explicit rule that shopping lines must be inside the fenced shopping-list block to be picked up downstream.
• Introduces a new “Recipes with more than one method” section explaining when and how to split variants into separate documents, including guidance on linking, shared components, and handling duplicate detection.

File summaries

File	Description
plugins-claude/meal-planning/skills/add-recipe/SKILL.md	Expands add-recipe documentation to cover fenced shopping-line requirements and the multi-variant (one-document-per-variant) recipe pattern.

Review details

Suppressed comments (1)

plugins-claude/meal-planning/skills/add-recipe/SKILL.md:284

• Same issue as above: this section says “grocery-cart never sees them”, but the cart step reads the plan’s shopping list. The key point is that ingredients outside the fenced list won’t be captured into the plan’s shopping list, so they can’t be carted. Adjust wording to avoid implying grocery-cart parses recipe fences.

variations on one. And a document that puts an alternate's ingredients in
prose after the fence loses them — `grocery-cart` never sees them, so the
protein for that version is never carted. Both failure modes have already

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.