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:

  1. Scaffold. Use How do I create a recipe?: compass add recipe. Slug convention: how_do_i_<thing>.
  2. Fill in the Question. Write the NLP question as the * Question heading — this is the load-bearing field for discovery.
  3. Write the Answer. Follow the recipe pattern: ordered steps with shell commands in #+begin_src sh :results verbatim blocks so they are executable in emacs (C-c C-c).
  4. Add Script and Tested-by. Point to the wrapper script if applicable; link to the CI check that exercises the recipe.
  5. Test the commands. Run every #+begin_src sh block to verify it produces the expected output. Update #+RESULTS: snapshots.
  6. Wire into the inventory. Add an id-link to the recipe in the topic's index file (e.g. doc/recipes/<topic>/<topic>.org).
  7. 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

Emacs 29.1 (Org mode 9.6.6)