Skip to main content
A definition file describes the knowledge for a subject or area of work. The protocol calls this a universe. Companion guidance explains how to answer its questions well. User definitions live in .knowledge-bus/ inside the folder they describe. See Knowledge Bus Directory for directory selection rules.

​
Definition and guidance files

The included example has two files: Guidance is optional. The universe must remain valid without it. When guidance is supplied, the checker validates its structure and references, not whether its advice is correct.

​
Field reference

The optional terms list names the universe’s own words, each with the one meaning it has throughout the definitions: { term, means }, each term once, compared case-insensitively. Terms carry no structure, and universes still correspond by question, not by term. For example, a frame could make a section required in one situation and unnecessary in another. A factor could select relevant writing advice without changing the required sections. A universe spec with elements names its ordering frame in the universe header. From kbp/0.9, a universe spec with no element, such as one declaring only factors, names no ordering frame. Guidance keyed to a factor is advice on presenting a document. An agent can apply the advice to the documents of any universe spec in the folder. The factor still adds or removes no section. The guidance file has a header (guidance), declared advice kinds (guidance_kinds), a source registry (sources), and entries attached to elements, artifacts, or factors.

​
Defining elements and artifacts

An element is identified by its question. Two candidate sections answering the same question refer to the same element, regardless of their headings. A document type is identified by the action or decision it enables and the actor who needs it. Its required contents are the information that actor needs to proceed. Other contents depend on the situation. Before adding a definition, compare it with existing questions and document purposes. You may need to clarify an existing definition rather than add another. /kb-uncover-question and /kb-evolve support that review.

​
Stable codes

Elements, artifact types, frames, and factors each carry a five-character code. The first character identifies the kind; the remaining characters have no encoded meaning. Codes do not encode meaning or order. People and agents use the readable id and question. Tools use the code to keep a stable reference when the same definition is renamed. Preserve its code and update references that use the changed id. Never reuse or reassign a retired code. From the repository root:
Replace the example path with your .knowledge-bus/ directory. This generates three element codes checked against its definitions. Use artifact, frame, or factor for other kinds. See Adapting the Example for use with your own definitions.

​
Requirements vs. recommendations

Put declarations and structural rules in the universe file. Put recommendations and their reasoning in guidance. For example, a rule requiring a section belongs in the document’s composition. Advice on writing that section clearly belongs in guidance. In the included guidance, conventions require registered sources. Other kinds, such as pitfalls and heuristics, may be marked asserted. Each guidance document declares which of its advice kinds require sources.

​
Validation scope

The checker validates supported structural rules in universe and guidance files. It does not yet fully validate instances or validate ingestion’s separate answers.yaml format. See Validation for commands and limitations.