Story: Runbook support

Table of Contents

This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Introduce a runbook as a new document type in the v2 information architecture. A runbook is a named, repeatable composition of recipes and skills — it captures the sequence that currently exists only in the LLM's inference. Where a recipe is a single operation and a skill is a unit-of-work playbook, a runbook chains them into a complete procedure with preconditions and postconditions. The user can say "begin work on X" and the LLM loads the corresponding runbook.

Status

Field Value
State DONE
Parent sprint Sprint 18
Now Complete.
Waiting on Nothing.
Next None.
Last touched 2026-05-28

Acceptance

  • A runbook is a recognised v2 document type with a defined frontmatter contract, required sections, and TODO state machine.
  • The ores.codegen scaffolds runbooks (--type runbook) with pre-filled preconditions, steps, and postconditions skeleton.
  • The compass tool supports compass add runbook and compass list --type runbook.
  • The glossary defines the term runbook.
  • At least one concrete runbook exists: "Start work on a new story" — the sequence from story scaffold through to PR creation.
  • The runbook references all steps by recipe id-link, never inline.

Tasks

Task State Start End Description
Implement runbook document type DONE 2026-05-26 2026-05-26 Add #+type: runbook to codegen, compass, glossary, and document types contract.
Implement runbook support DONE 2026-05-26 2026-05-28 Add runbook document type to codegen, compass, glossary, and document types; write concrete runbook.

PRs

PR Title
860 [agile] Add runbook-support story to sprint 18

Plan

The current information architecture has fine-grained recipes (single operations) and skills (unit-of-work playbooks). But nothing captures the sequence that chains them. An LLM must discover the order by inference — which is fragile, slow, and unrepeatable. The user should be able to say "begin work on X" and have the system load a composed procedure.

A runbook fills this gap. It is to recipes what a meal is to individual cooking steps: a named DAG of steps, each referencing a recipe by id-link.

Runbook structure

A runbook carries #+type: runbook and lives under doc/runbooks/. Required sections:

  • * Goal — what this runbook achieves, in one sentence.
  • * Preconditions — what must be true before starting (e.g. "you are on main", "current sprint exists").
  • * Steps — an ordered list. Each step references a recipe or skill by id-link, with a one-line description of what happens at that step.
  • * Postconditions — what is true after completing (e.g. "feature branch exists", "story is STARTED", "PR is open").
  • * See also — external links.

A step may optionally name a skill to load before the recipe. Steps are ordered but may include branching ("if declined, go to step N").

Taxonomy placement

Runbooks are owned by System 2 (Orchestrator) — they coordinate S1 operations (recipes) into higher-level procedures. They sit between functions (role-shaped priming) and recipes (single operations).

Deliverables

  1. Document type contract. Update document types with the runbook contract: frontmatter fields, required sections, TODO states, filename conventions.
  2. Codegen support. Add --type runbook to generate_v2_doc.sh with a mustache template that pre-fills Goal, Preconditions, Steps, Postconditions, and See also sections.
  3. Compass support. Add compass add runbook (scaffolds into doc/runbooks/) and compass list --type runbook (filters the doctype taxonomy).
  4. Glossary entry. Define runbook in glossary with a stable id-link.
  5. Concrete runbook. Write doc/runbooks/start_new_story.org — the end-to-end procedure for "begin work on X" that chains: compass add story → feature branch → fill content → mark STARTED → wire into sprint → commit → push → PR.

Dependencies

  • ores.codegen — add runbook to the type enum, template, and tag injection.
  • compass — wire runbook into the Scaffold and Locate pillars.
  • Document types — the contract source.
  • Glossary — the vocabulary source.

Decisions

  • Naming: runbook chosen over workflow (the latter already has a specific meaning in the ORE Studio codebase for saga orchestration).
  • Location: doc/runbooks/, not doc/agile/runbooks/ — runbooks may span beyond agile operations (build, release, audit).
  • Steps reference recipes by id-link, never inline — the recipe is the single source of truth for how-to.

Review

Review round 1 (gemini-code-assist, 2026-05-26).

# Comment summary File Decision Notes
1 Empty Tasks bullet (line 45) story.org Applied Already fixed in ea79db188: replaced by * PRs

Out of scope

  • Automatic execution of runbooks (a compass run command). The runbook is a documented sequence for LLM consumption, not an execution engine.
  • Runbook versioning or branching — initial delivery is linear sequences only.
  • Migration of existing documentation into runbooks beyond the single concrete example.

Emacs 29.1 (Org mode 9.6.6)