Why notes have types

Type: note · Status: seedling

The type system serves six distinct roles. Each is developed in its own note; 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.

Output quality

Types don't just organise — they 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, three independent arguments support this:

The arguments are independent and complementary. Each stands alone; together they cover the full chain: the LLM might reason better, the output will be shaped better, and the human reader can evaluate it better.

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 frontmatter (note) → 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 stabilisation pattern: practices start stochastic and harden as they prove out.

Why free-form, not enum

The type field is a string, not validated against a list. This is deliberate:

  • 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.
  • Tolerance of fuzziness. Types are assigned by agents and humans, not compilers. The system must tolerate misclassification — nothing breaks if a type is wrong or novel. Types are search aids, not enforcement boundaries.

Convention establishes common values. Directory types/ folders document structural expectations. But the system doesn't require permission to use a new value.

Relevant Notes:

Topics: