Document system

Type: kb/types/tag-readme.md

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 how the live Commonplace system uses global and collection-local type contracts, see collections and types.

Foundations

• note base type — the base structured type: required path-valued type and description, optional traits and tags, and optional committed human verification
• 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
• opposed recompute factors do not decide documentation segmentation — crossed savings and recurrence rankings need measured magnitudes even to order cache value, while segmentation also depends on whether specialization repays another maintained content layer
• addressability grain, not compression ratio, sets a matched selective-read floor — for a known question with one discriminating unit on each path, the smaller addressed unit sets the retrieval floor; opposite Commonplace cases show why whole-artifact compression does not decide it
• 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
• a-universal-knowledge-framework-demotes-content-taxonomies-to-defaults — type and label taxonomies are open local choices, while the former register taxonomy became clone-once collection prototypes; the fixed points are stipulated answerability and enforced contract declaration, not certified universals
• A framework rule with a boundary-preserving rival is not an inherited constraint — the complement: a one-way demotion test — a rule whose rival preserves the boundary invariants (consumer, substrate, domain, machinery) is a design choice; a rule with no rival found is only undemoted, not certified

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
• domain-pricing-routes-an-exception-to-idealization-assessment — the workflow shape for defeated-but-retainable claims: domain pricing opens an idealization assessment, adequacy evidence decides it, and pricing-gated acceptance is an immunizing slot

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 storage substrate 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 citation cannot assert more fidelity than its capture preserved - Capture is layered (verbatim / paraphrase / second-hand) by forced constraints; a citation's fidelity is bounded by which layer holds the passage, and no notation can raise it — only re-capture
• A specific intent may out-yield local rationales, but contingent facts stay separate - Conjectures that an unrecoverable governing intent yields more local rationale per token than rationale snippets, while contingent design facts need their own record
• An artifact must preserve the scope of each named system choice - An artifact may inherit scope from context guaranteed to its consumers; for each named system choice it must preserve a proposition-relative reference rule or range plus the choice's role, not necessarily concrete identity or quantifier syntax
• An enforced tag-README combines a MOC pattern with checked membership - A Commonplace tag-README can inherit Milo's contextual mapping pattern while validation checks only its declared membership relations, not editorial quality.
• An insufficient summary precedes the source rather than replacing it - When a summary cannot license a reliability-compliant stop, the authoritative fallback remains in the path; only fallback work the summary removes can offset its own cost
• Artifact classification separates content kind, lineage, and authority - Use this note to classify retained KB artifacts without conflating content kind, production lineage, or path-relative behavioral authority with the collection's local writing contract.
• Cheap adoption and weak retirement accumulate cost - Explains why locally cheap structural additions become routing, maintenance, and migration debt when retirement needs distributed evidence and lacks an equally operative path.
• Coordination value - Definition — coordination value is the worth a shared structure has because adopters commit to the same one; created by the commitment rather than discovered as a property of the choice, so a better-in-principle rival does not increase it
• Current-task fit alone does not warrant costly structural entrenchment - Distinguishes reversible adoption from costly structural entrenchment and confines option reasoning to the timing of a commitment supported by an enduring constraint, scoped transfer warrant, or actual coordination value.
• Design rationale must preserve decision premises its interpreter cannot regenerate - Retention test for source-checkout design rationale: keep current decision premises not faithfully recoverable from implementation, git, and general knowledge; treat recoverable, role-free explanation as a cache
• Directory placement is total, frontmatter classification is partial - Canonical paths cover every file before validation and supply locality; opt-in types supply portability. Validation can encode similar policy on either surface, but native guarantees differ.
• Generality bought to avoid counterexamples is paid for in precision - Widening a claim's vocabulary to survive counterexamples raises universality by spending precision, so content stays flat — and the unreadability that follows is the symptom, not the price of rigor
• Narrowing bought to survive review is paid for in content - Repairing a defeated claim by shrinking its subject is justified at every step, but shrinking the subject into the predicate's own extension yields an analytic title that passes every gate and says nothing.
• Technical constraints turn KB objective-function choice from philosophy into engineering - Three technical constraints and the codification lever make KB objective-function choice testable engineering, not philosophy; goals set the loss, local contracts specialize it, and oracle strength differs by objective
• Three simplification passes exposed different clarity–precision tradeoffs - Evidence from three independent rewrites of one mature article: broad style guidance ranked best overall, a compact style cue improved rhythm but drifted, and exhaustive local review barely changed the text
• Two rewrites exposed a syntax-or-repetition tradeoff - Evidence from two ASD-STE100-inspired passes over one note: unguarded sentence splitting lost semantic relations, while guarded splitting preserved them by adding 4.9% more words