Add a new knowledge document

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 knowledge document: scaffold, fill in the durable factual content, and wire it into the knowledge index under the appropriate topic.

Preconditions

  • The topic is clear (domain concept, architecture decision, convention, etc.).
  • The target topic folder exists under doc/knowledge/<topic>/.

Steps

In execution order:

  1. Scaffold. Use How do I create a new doc?§"New knowledge document": compass add knowledge.
  2. Fill in the Summary. Write the three-to-five sentence summary — the load-bearing field that every grep and index reads.
  3. Write the Detail. Fill in the content. Use subheadings for navigability. Every reference to another doc uses [[id:UUID]] links.
  4. Tag correctly. Add topic tags (:domain:fx:, :architecture:cmake:, etc.) so the doc is discoverable by compass list.
  5. Wire into the inventory. Add an id-link under the appropriate topic heading in Knowledge.
  6. Commit and PR. Use commit conventions and create a PR.

Postconditions

  • Knowledge doc has all required frontmatter and sections.
  • Doc is linked from the knowledge index.
  • PR is open.

See also

Emacs 29.1 (Org mode 9.6.6)