> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge-bus.pdflowlabs.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Adapting a sample

> Start with one of the universes included in `universe-samples/`, keep what fits your work, and change what does not.

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](https://knowledge-bus.pdflowlabs.io/docs/knowledge-bus-directory.md).

## Choose a starting point

| Approach | When it fits |
| - | - |
| Adopt | The questions, document purposes, and requirements fit your work. |
| Trim | The definitions fit, but your work needs only part of them. |
| Extend | The structure fits, but a question, document type, or relationship is missing. |
| Develop your own | Your subject or work needs substantially different questions and document purposes. |

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`](https://github.com/SterlingJF/knowledge-bus/blob/main/skills/kb-evolve/SKILL.md) 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](https://knowledge-bus.pdflowlabs.io/docs/spec-anatomy.md) 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](https://knowledge-bus.pdflowlabs.io/docs/how-ingest-works.md).

## Assign stable codes

Each new element, document type, frame, or factor needs a code. From the repository root, generate three element codes with:

```bash theme={null}
uv run kbp --mint element 3 path/to/project/.knowledge-bus/
```

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](https://knowledge-bus.pdflowlabs.io/docs/validation.md) for commands and coverage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.