fix(aidd-context): restore readable recipe authoring

Keep the original Markdown scaffold adaptable and let validation reject broken recipes without imposing editorial heuristics. Make file reads and symlinked entry points reliable.
alexsoyes · Jul 26, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 27, 2026
commit 74d1c18a36d9fa378f808db8f2af1ff2c67e545c
@@ -0,0 +1,40 @@
+# Review: Cook recipe authoring cleanup
+
+- **Verdict**: approve
+- **Diff**: `ff28a45c...HEAD`
+- **Axes run**: code, functional, relevancy
+- **Date**: 2026_10_01
+- **Findings**: 0 critical, 0 warning, 0 minor
+
+## Phases
+
+### Phase 1: Recipe authoring
+
+- [x] Restore the original English Markdown scaffold with optional sections: `plugins/aidd-context/skills/12-cook/assets/recipe-template.md:1`.
+- [x] Keep nine concise contract principles without duplicated scaffolding: `plugins/aidd-context/skills/12-cook/references/recipe-contract.md:3`.
+- [x] Preserve standalone routes, repair routing, action tests, and catalog consistency: `plugins/aidd-context/skills/12-cook/SKILL.md:9`, `plugins/aidd-context/skills/12-cook/actions/02-upsert.md:28`, `plugins/aidd-context/skills/12-cook/actions/05-validate.md:22`.
+
+### Phase 2: Reliable validation
+
+- [x] Accept useful Markdown variants while reporting broken structure, examples, and links: `scripts/__tests__/validate-recipe.test.js:139`.
+- [x] Read and inspect the same file descriptor, close it, and report read failures: `plugins/aidd-context/skills/12-cook/scripts/validate-recipe.mjs:39`.
+- [x] Run through symlinked entry points without executing on library import: `plugins/aidd-context/skills/12-cook/scripts/validate-recipe.mjs:498`, `scripts/__tests__/validate-recipe.test.js:391`.
+- [x] Remove punctuation-based description false positives and keep the RTK recipe correction scoped to step 19: `scripts/__tests__/validate-recipe.test.js:208`, `plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md:383`.
+
+## Findings
+
+None.
+
+## Verification
+
+| Metric | Value |
+| --- | --- |
+| Verified | 7/7 cleanup criteria |
+| Files checked | Nine staged cleanup files; independent checker reviewed code, behavior, and relevance |
+| Unchecked | None within the bounded cleanup review |
+| Unplanned | None |
+| Checker execution | 26 guarded validator tests passed; bundled validation returned `PASS: 3 recipe(s) validated.` |
+| Main execution | Global pre-commit passed: 575 script tests, 140 CLI architecture tests, typecheck, lint, manifests, paths, and links |
+| Snippet syntax | 4 JSON, 2 YAML, 8 TOML, and 9 shell examples parsed successfully |
+| Distribution execution | Fresh Codex flat and Claude marketplace builds each returned the exact three-recipe PASS output |
+| Limits | CodeQL and the new commit's remote CI remain to be checked after push; interactive client workflows were not executed |
@@ -215,5 +215,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `references` | [recipe-contract.md](skills/12-cook/references/recipe-contract.md) | - |
 | `references` | [recipe-locations.md](skills/12-cook/references/recipe-locations.md) | - |
 | `references` | [research-playbook.md](skills/12-cook/references/research-playbook.md) | - |
-| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage project recipes/how-to sheets by listing, creating, updating, researching, applying, or validating a recipe. Use for recipe, cook, /cook, list, new, update, research, apply, validate.` |
+| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manages project recipes and practical guides. Use when the user wants to find a recipe, document a technique, research improvements, follow an existing guide, or check that its steps are usable.` |
 
@@ -1,6 +1,6 @@
 ---
 name: 12-cook
-description: Manage project recipes/how-to sheets by listing, creating, updating, researching, applying, or validating a recipe. Use for recipe, cook, /cook, list, new, update, research, apply, validate.
+description: Manages project recipes and practical guides. Use when the user wants to find a recipe, document a technique, research improvements, follow an existing guide, or check that its steps are usable.
 argument-hint: recipe
 ---
 

@@ -20,15 +20,17 @@ The recipe file at `aidd_docs/recipes/<slug>.md`, filled from the template.
 4. **Ask.** Ask only for a missing decision that changes the recipe's outcome or scope.
 5. **Dedup.** For a new recipe, run `list` and rate each near match in an overlap table `| Existing recipe | Source | Shared scope | Overlap |`, where `Overlap` is none, partial, or high.
    - On any `high`, recommend updating that recipe instead and ask update-or-create before scaffolding.
-6. **Scaffold.** Scaffold from [recipe-template.md](../assets/recipe-template.md) when needed, applying [recipe-contract.md](../references/recipe-contract.md) to every section while preserving verified commands, examples, limits, screenshots, and evidence and deleting narrative repetition.
+6. **Scaffold.** Use [recipe-template.md](../assets/recipe-template.md) when needed and apply [recipe-contract.md](../references/recipe-contract.md), preserving verified useful content on updates.
 7. **Fill.** Fill every placeholder. Never maintain a separate recipe index; `list` reads the files directly.
 8. **Validate.** Run `validate` (05) after the write.
    - On findings, return to Scaffold and Fill to repair the recipe, then rerun both checks until they pass; reuse verified research rather than restarting it for repairs.
 
 ## Test
 
-- A new or substantially-updated recipe is drafted from `research` results, not from memory.
-- `aidd_docs/recipes/<slug>.md` exists and passes the recipe contract.
-- `validate` passes after the write; no validation finding is silently waived.
-- A bundled recipe is never overwritten unless the user explicitly asks to change a bundled/framework recipe.
-- A new recipe that highly overlaps an existing project or bundled recipe triggers an update-or-create prompt before scaffolding.
+| Case | Pass |
+| --- | --- |
+| New or substantially updated recipe | The draft uses verified research results rather than memory |
+| Project recipe written | `aidd_docs/recipes/<slug>.md` exists and passes the recipe contract |
+| Validation after writing | Both checks pass and no finding is silently waived |
+| Bundled recipe selected | It is overwritten only on an explicit bundled/framework change request |
+| High overlap with an existing recipe | An update-or-create prompt precedes scaffolding |
@@ -21,7 +21,9 @@ Validation is read-only. Never repair, reformat, or rewrite a recipe during this
 
 ## Test
 
-- One valid recipe and `all` return PASS without changing tracked files.
-- A structural failure returns the validator table with file, line, rule, fix, and a non-zero exit code.
-- A semantic failure appears in the same table even when the deterministic script passes.
-- JSON is parsed mechanically; YAML, TOML, and shell use available tools, and unavailable parsers appear in the success summary or a relevant failure.
+| Case | Pass |
+| --- | --- |
+| One valid recipe or `all` | PASS is returned without changing tracked files |
+| Structural failure | The table includes file, line, rule, and fix, with a non-zero exit code |
+| Semantic failure after deterministic PASS | The finding appears in the same table |
+| Snippet syntax | JSON is parsed mechanically; available YAML, TOML, and shell tools are used, and unavailable parsers are disclosed |
@@ -1,19 +1,52 @@
-<!-- Fill every placeholder, repeat the step scaffold as needed, and remove all scaffold comments from the finished recipe. Keep the H1 title, plain description sentence, then the steps in this order. -->
-# <!-- Recipe title -->
+# <Recipe title>
 
-<!-- Write one plain sentence naming the observable outcome. -->
+<One sentence describing what this recipe gets the reader.>
 
-<!-- Add an optional table of contents between the description and steps only when the finished recipe has at least 10 steps; omit it from shorter recipes. -->
+> Fill every placeholder and remove these instructions. Omit Why, Verify, and difficulty categories when they add no value; without categories, use direct `### N) <emoji> Title` steps.
 
-## Steps to <!-- outcome -->
+## Why
 
-<!-- Name this section for the outcome, never just Steps. Use ### N) <emoji> Title for direct steps, or #### N) <emoji> Title under a ### category. Optional difficulty categories are ### 🟢 Beginner, ### 🟡 Intermediate, and ### 🔴 Expert. Number steps continuously across categories. -->
-### 1) <!-- emoji + action title -->
+<Short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms.>
 
-<!-- Start with one sentence naming the benefit or risk, and state where and when this applies. -->
-<!-- Add only the actions needed to perform and verify the technique. Number them when there is more than one. -->
-<!-- Include one typed, copyable command/config/output, concrete table, or operational image from a real source. -->
+## Steps to <the outcome the reader achieves>
+
+### 🟢 Beginner
+
+#### 1) <emoji> <First step title>
+
+<One benefit-focused line of what and why, in prose.>
+
+1. <where it is, then install it from its URL>
+2. <how to invoke it — its real command or slash>
+
+```bash
+$ <command the reader runs>
+<the useful output it prints, trimmed to what matters>
+```
+
+### 🟡 Intermediate
+
+#### 2) <emoji> <Next step title>
+
+<Benefit-focused what and why, in prose.>
+
+1. <action>
+2. <action>
+
+```<lang>
+<a config or snippet the reader can copy>
+```
+
+### 🔴 Expert
+
+#### 3) <emoji> <Last step title — until the goal is reached>
+
+<Benefit-focused what and why, in prose.>
+
+1. <action>
+
+![<what this screenshot or video shows>](<path-or-url>)
 
 ## Verify
 
-<!-- Add an observable command output, UI state, or file check; omit only when no useful check exists. -->
+- <Optional. An observable check that proves it worked: a command, a UI state, a file that now exists.>
@@ -384,16 +384,16 @@ See [`SNIP`](https://github.com/edouard-claude/snip).
 
 #### 19) 🪝 Automate RTK where supported
 
-Claude Code rewrites eligible Bash calls through a hook; Codex installs `AGENTS.md` guidance and still relies on the agent invoking RTK.
+RTK rewrites eligible shell calls through hooks in Claude Code and Codex CLI when the host supports and trusts the installed hook.
 
 ```bash
 rtk init -g                    # Claude Code hook
-rtk init -g --codex            # Codex instructions
+rtk init -g --codex            # Codex CLI hook + AGENTS.md + RTK.md
 rtk init -g --uninstall        # Remove the Claude Code integration
 rtk init -g --codex --uninstall # Remove the Codex integration
 ```
 
-Verify Claude Code with `/hooks`. For Codex, inspect the generated `AGENTS.md` and `RTK.md`; do not assume transparent rewriting. See [RTK's current client matrix](https://github.com/rtk-ai/rtk/blob/develop/README.md#supported-ai-tools) and [Claude Code filtering hooks](https://code.claude.com/docs/en/costs#offload-processing-to-hooks-and-skills).
+Verify Claude Code with `/hooks`; in Codex CLI, inspect the generated hook, `AGENTS.md`, and `RTK.md`, confirm hook trust, then check that an eligible shell call is rewritten. See [RTK's current client matrix](https://github.com/rtk-ai/rtk/blob/develop/README.md#supported-ai-tools) and [Claude Code filtering hooks](https://code.claude.com/docs/en/costs#offload-processing-to-hooks-and-skills).
 
 #### 20) ✋ Cap Codex tool history
 

@@ -1,42 +1,19 @@
-<!-- Cited by upsert and validate. The rules every recipe file follows. -->
-
 # Recipe contract
 
-Rules for every recipe file the skill writes.
-
-## File
-
-- Project path: `aidd_docs/recipes/<kebab-slug>.md`.
-- Follow the layout and heading format in `assets/recipe-template.md`.
-- The description has no "Goal:" label, blockquote, or metadata table.
-- End with at most one short conclusion. Never add a `## Related` section: links live inline where they are used.
-- Never add `## Why`: the description states the outcome and each technique states its own benefit or risk.
-- Every table-of-contents anchor must resolve.
-
 ## Writing
 
-- Write for execution: preserve commands, configurations, examples, screenshots, limits, evidence, and verification; remove narrative, repetition, transitions, and theory that do not change an action.
-- One idea per sentence. Prefer removing over adding.
-- No filler line under a heading (no "Ranked by impact", "Start at the top", and the like).
-- Distinguish primary and secondary benefits. State conditional, neutral, and net-negative cases instead of implying a universal win.
+- Keep prose that helps the reader perform, understand, or verify the technique.
+- State where and when a technique applies.
 
 ## Steps
 
-- Heading levels express nesting. Never skip a level: a heading may be at most one level deeper than the heading before it.
-- One step = one technique named for its action. Split distinct responsibilities, inputs and outputs, alternatives, or tools unless comparing them is the technique.
-- Add prose only when it is required to operate, verify, or bound the technique.
-- A single command, configuration, or example may stand alone. Write descriptions as prose, never as a bullet.
-- State applicability and location for every technique. For an installed tool or persistent configuration, also give the official installation, real invocation, and stop, disable, or rollback path when available; state explicitly when the official source documents no reversal.
-- Reuse the tool's canonical example captured verbatim from its site or README — never a paraphrase, and never on the strength of a summary that says one exists.
-- Every step carries a copyable, syntactically valid example. Prefer an image — a screenshot or short video/GIF that matches the action — when it adds operational information; for a tool, use its official screenshot when available. Otherwise use a command with real output, a config in the file's real syntax, or a snippet.
-- Compare alternatives in a table, not prose. Test each mechanism alone before recommending a combination; state conflicts and ordering.
-- For a structural or flow concept (a proxy, a pipeline, an architecture), add a small Mermaid diagram with concrete example values.
-- Group steps by difficulty only when the recipe spans levels and grouping helps the reader. Include only levels that have a step.
-- Link to a reference when applicable.
+- One step covers one technique, named for its action.
+- Headings express nesting without skipping a level; number steps continuously from 1 across categories.
+- Give each step a concrete, usable command, configuration, output, table, or operational image; code examples must be syntactically valid.
+- Local links and table-of-contents anchors must resolve; remove unfinished placeholders.
 
 ## Evidence
 
-- Verify commands, configuration keys, compatibility, and behavior against current official documentation. Record a version or publication date when the source can drift; prefer immutable or pinned references for reproducible assets.
-- Make the evidence class clear from the sentence or source framing: **independent measurement**, **maintainer claim**, or **inference**. A linked first-party behavior claim is a maintainer claim without needing a repeated label; qualify anything whose strength is not obvious. Never turn an inference or unverified summary into a fact.
-- Do not promise token, time, cost, or quality savings without a published measurement. State the workload and caveat when a result may not transfer.
-- Compare benchmarks with the same model, effort, task, and quality gate. Count input, output, reasoning, tool output, and subagent overhead; a smaller main context is not automatically lower total usage.
+- Verify commands, configuration, and behavior against current official sources; link them where they are used.
+- Qualify claims as measurements, maintainer claims, or inferences when their strength is not obvious; state relevant conditions and limits.
+- Support promised savings with measurements and their workload; never present an unverified claim as fact.