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:
- Scaffold. Use How do I create a new doc?§"New knowledge document":
compass add knowledge. - Fill in the Summary. Write the three-to-five sentence summary — the load-bearing field that every grep and index reads.
- Write the Detail. Fill in the content. Use subheadings for navigability. Every reference to another doc uses
[[id:UUID]]links. - Tag correctly. Add topic tags (
:domain:fx:,:architecture:cmake:, etc.) so the doc is discoverable bycompass list. - Wire into the inventory. Add an id-link under the appropriate topic heading in Knowledge.
- 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
- Knowledge index — all knowledge documents.
- Runbooks catalogue — all runbooks.