Why notes have types

Type: kb/types/note.md · Tags: type-system

The type system serves seven distinct roles. Each is developed in its own note or nearby collection-and-type theory; this page provides context and links.

Agents are stateless and context is finite. Types give agents structural hints before opening documents — a spec says "you can implement from this," a structured-claim says "there's a developed argument with evidence," an index says "follow links from here." The type plus description let an agent narrow from hundreds of files to the few it needs without opening any of them.

Metadata enforcement

Navigation depends on metadata existing reliably. The type system enforces metadata that navigation depends on — descriptions exist because the note base type requires them. Without enforcement, agents and humans under time pressure skip metadata, and the knowledge base degrades to a collection navigable only by opening every document.

Verification

Types must assert verifiable structural properties, not subject matter. "This is a design note" is not verifiable — every note in a design KB is about design. "This has Evidence and Reasoning sections" is verifiable. The verification gradient means types can be checked at different levels of cost — from deterministic (does the frontmatter have a description?) through LLM rubric (is the description discriminating?) to corpus-level (does this contradict existing claims?).

Extensibility

Different knowledge domains need different document structures. Directory-scoped types are cheaper than global types — the global layer stays thin (text and note), while each collection has its own types/ subdirectory with templates that extend the base. This keeps per-session context cost low and lets users introduce new types by adding a template locally, with no global configuration changes.

Collection and type remain separate inputs

Types do not identify the local writing contract. The containing path selects the collection's COLLECTION.md, while type: selects a structural and semantic type contract. A note in kb/notes/ therefore receives explanatory-reach from the notes collection; a note in kb/reference/ receives fidelity and economy from the reference collection. The same type can compose with different local quality goals without changing its own meaning.

This connects the type system to the classifier that separates content kind, lineage, and authority. Validation and review can combine the independently resolved collection and type contracts without adding a duplicate frontmatter field. Neither contract classifies every region or consumption path.

Output quality

Beyond organisation, types shape what gets written. When a structured-claim template requires Evidence, Reasoning, and Caveats sections, the writer must actually produce those things. With LLMs specifically, two arguments support this role and one evidential limit prevents overclaiming its mechanism:

The two positive arguments are independent, while the causal limit keeps their benefits from being misattributed. Together they justify structure through the work it requires and the review it enables without assuming a training-data mechanism.

Maturation

Content starts as text (no frontmatter, no structure) and gains type information as it develops — gradual typing applied to documents. The maturation path is: raw capture → add valid note frontmatter (description plus type: kb/types/note.md) → accumulate traits → promote to a specific type when structural criteria are met. A bare note that persists without promotion is a signal. This mirrors the broader constraining pattern: practices start stochastic and harden as they prove out.

Why path-valued, not a closed enum

The type field points to a type-spec document rather than selecting from one framework-wide enum. This keeps the set extensible without making type identity free-form:

  • New domains. Workshop documents, scenario types, recurring tasks — these emerged after the initial type system. A closed enum would have required updating a global definition for each.
  • User adaptation. Installed knowledge bases serve different purposes. A research project might need experiment and literature-review types. A product team might need user-story and retrospective. These should be addable locally.
  • Path identity. A new value is valid only when its path resolves to a real type spec. Different paths remain different contracts even if their specs use the same shorthand name.

Type choice remains a fallible authoring judgment, but the selected contract is an enforcement boundary: its schema and type-conformance review apply to the artifact. Extensibility comes from adding a type spec, not from inventing an unresolvable value.

Relevant Notes: