Skip to main content
Start with one of the universes included in universe-samples/, keep what fits your work, and change what does not. You can do this before writing any documents.

​
What the starter contains

The starter defines questions, the document types that hold them, the relationships between them, and guidance that cites registered sources. It covers documents such as strategy canvases, decision records, design documents, and experiment plans. Run uv run kbp in a clone to see current counts. Its questions can be useful at different scales, from a personal project to a company. Review the definitions against your own purpose, audience, and requirements before adopting them. Keep your definitions in .knowledge-bus/ inside the folder they describe. Guidance is optional; ingestion outputs are not required to start. See Knowledge Bus Directory.

​
Choose a starting point

For example, a solo project may need a decision record without the full set of product-planning documents. A research project may need definitions for evidence and methods that the starter does not cover. When trimming, check references between definitions. Removing one may affect the document types, relationships, or guidance that use it.

​
Add or review a document type

Use /kb-evolve when a document type is missing or when you want to examine an existing type before relying on it. The skill helps establish:
  • what decision or action the document supports, and for whom;
  • which questions its contents answer;
  • whether those questions or document purposes already exist;
  • which information is required and which depends on the situation;
  • which relationships and guidance need to change.
It researches the proposed type, checks the resulting files, and records the changes and their reasons, including proposed additions it rejected. Before writing, the skill shows one table per universe spec: each change with its location, current text, proposed text, evidence and reason. You answer by row number. After writing, the skill shows each change before and after. Use /kb-uncover-question when you need help clarifying a question or distinguishing it from existing ones. Guided creation of an entire new set of definitions remains planned work. You can author one directly using Spec Anatomy and check it with the current tools.

​
Apply definitions to existing notes

If you already have notes, /kb-ingest reviews them and proposes whether to adopt, adapt, or develop definitions for that material. It asks you to confirm the proposed approach. Content that does not fit may indicate a missing definition or material outside the chosen scope. Review the reason before changing the structure. See How Ingest Works.

​
Assign stable codes

Each new element, document type, frame, or factor needs a code. From the repository root, generate three element codes with:
Use artifact, frame, or factor for the other declaration kinds. Replace the example path with your .knowledge-bus/ directory so generated codes are checked against its existing definitions. Keep the code when renaming the same definition. Never reuse or reassign a retired code. Update any references that use the renamed id.

​
Add guidance and check the result

In the included guidance, a convention must cite a registered source. Other kinds can use asserted to identify advice supplied without an external citation. Preserve sourcing limitations, such as abstract-only access or a rescinded source, in the citation. Run the checker with both the definition and guidance files after editing. Passing means the files satisfy the structural checks currently implemented. You still need to review whether the definitions and advice fit your work. See Validation for commands and coverage.