Document system

Type: kb/types/tag-readme.md · Status: seedling

How documents are classified, structured, and quality-checked. These notes define the type system, writing conventions, and testing framework that make knowledge artifacts machine-verifiable and human-readable.

For the live Commonplace repo's current type inventory and migration summary, see ../reference/available-types.md.

Foundations

• note base type — the base structured type: global fields (description, status, traits, areas), status ladder, traits system, design principles
• text root type — the empty root type: no frontmatter, always valid
• human-llm-differences-are-load-bearing-for-knowledge-system-design — knowledge systems produce dual-audience documents (human + LLM), making cognitive differences a first-class design concern for type and convention design
• why-directories-despite-their-costs — directories buy one-two orders of magnitude of navigable scale but each new directory taxes routing, search config, and cross-directory linking

Writing Conventions

• title-as-claim-enables-traversal-as-reasoning — claim titles make link traversal read as reasoning chains; topical titles break this, and multi-claim documents get different title conventions

Testing

• automated-tests-for-text — text artifacts can be tested with the same pyramid as software: deterministic checks, LLM rubrics, corpus compatibility
• text-testing-framework — reference framework: contracts per document type, test pyramid (deterministic/LLM rubric/corpus), production workflow
• deterministic-validation-should-be-a-script — half of /validate's checks are hard-oracle (enums, link resolution, frontmatter structure) and could run as a Python script instead of burning LLM tokens
• unit-testing-llm-instructions-requires-mocking-the-tool-boundary — skills are programs whose I/O boundary is tool calls; mocking that boundary enables instruction-level testing that complements text artifact testing

Decisions

• 002-inline-global-types-in-writing-guide — inline note and structured-claim templates into WRITING.md, eliminating one hop for the two most common note types

Related Tags

• type-system — sub-area: why documents have types, their roles, and how structured writing improves quality
• tags — the document system is infrastructure for the KB; architecture decisions about files-not-database and context loading depend on document structure
• links — title-as-claim bridges both areas: it's a writing convention that enables link semantics
• learning-theory — the type ladder instantiates the constraining gradient for documents

Other tagged notes

• A knowledge base holds theories, descriptions, and prescriptions with asymmetric linking - Three exhaustive registers — theory, description, prescription — with distinct quality goals; formulation constraint and maintenance asymmetry make the split real, distillation connects them; registers classify content orthogonally to operational roles, and in agent systems the prescription/implementation boundary collapses
• Design for the first-time human, except on access cost - Treating an LLM agent as a competent first-time human is a good default for designing the systems it consumes — on most affordances. The proxy breaks on access cost, because humans read large artifacts sublinearly while agents load them whole into bounded context.
• Design proposals differ from claims in kind, not confidence - A hypothesis is a claim at reduced commitment; a design proposal is not truth-apt at all — free parameters make it evaluable by usefulness, not truth. A proposal with substantive requirements can re-enter a claims register as an existential claim with the construction as witness
• Register - Definition — a register is one of three content modes (theoretical, descriptive, prescriptive) that determines a collection's quality goal, title conventions, and linking rules