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
• design-for-the-first-time-human-except-on-access-cost — refines the dual-audience heuristic: design for newcomer-human ergonomics except where agent access mode makes whole-artifact reads expensive
• 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
• An enforced tag-README is a MOC with a machine-checked contract - Tag-READMEs inherit the Zettelkasten/LYT Map-of-Content tradition; the complete/covered_by marks add a completeness contract human PKM never made — humans neither needed nor could cheaply enforce it
• 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