Create a new recipe
Table of Contents
This page documents a runbook — a named, repeatable composition of recipes and skills for a complete multi-step procedure. Each step references a recipe or skill by id-link.
Goal
Create a new recipe: scaffold, fill in the required sections, test the shell commands, and wire it into the recipes inventory.
Preconditions
- The question the recipe answers is clear.
- The topic folder exists or will be created under
doc/recipes/<topic>/.
Steps
In execution order:
- Scaffold. Use How do I create a recipe?:
compass add recipe. Slug convention:how_do_i_<thing>. - Fill in the Question. Write the NLP question as the
* Questionheading — this is the load-bearing field for discovery. - Write the Answer. Follow the recipe pattern: ordered steps with shell commands in
#+begin_src sh :results verbatimblocks so they are executable in emacs (C-c C-c). - Add Script and Tested-by. Point to the wrapper script if applicable; link to the CI check that exercises the recipe.
- Test the commands. Run every
#+begin_src shblock to verify it produces the expected output. Update#+RESULTS:snapshots. - Wire into the inventory. Add an id-link to the recipe in the topic's index file (e.g.
doc/recipes/<topic>/<topic>.org). - Commit and PR. Use commit conventions and create a PR.
Postconditions
- Recipe is scaffolded with all required sections.
- Shell commands are tested and produce correct output.
- Recipe is linked from its topic's inventory page.
- PR is open.
See also
- How do I create a recipe? — the detailed recipe.
- Recipes index — all recipes.
- Runbooks catalogue — all runbooks.