Document system

Type: types/tag-readme.md

This tag gathers how KB documents are typed, written, structured, and checked: document types and type contracts, writing conventions such as claim titles, testing and validating text, how directories and taxonomies organize a KB, what documentation to retain and how to segment it, and how defeated claims get repaired. No single defining note anchors it; human-LLM differences are load-bearing states the dual-audience premise most members build on. Members are mostly notes, plus a reference definition and a reference proposal. Nearby but different: artifact-analysis classifies any retained artifact by substrate, form, lineage, and authority; a note belongs here when its question is how a document is written, structured, or checked.

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 — hard-oracle checks (enums, link resolution, frontmatter structure) belong in a script, not an LLM skill; the argument behind what is now commonplace-validate
• 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

Claim Quality and Repair

• generality bought to avoid counterexamples is paid for in precision — widening a claim's vocabulary to survive counterexamples keeps content flat; unreadability is the symptom
• narrowing bought to survive review is paid for in content — shrinking a defeated claim's subject can end in an analytic title that passes every gate and says nothing
• 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

• 084-kind rules live in type specs and operations in instructions — where a document kind's rules are stated and where its procedures live; the collection contracts (COLLECTION.md) replaced the old writing guide

Related Tags

• type-system — sub-area: why documents have types, their roles, and how structured writing improves quality
• architecture — storage substrate and layout decisions that 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 compact, refreshable whole-picture narrative can replace infeasible fragment reconciliation - Holistic rewrite shifts reconciliation from each consumer to the author, but only when the whole-picture narrative can fit within effective context and be refreshed before the narrative goes stale
• A linked note's durable payload is what its consumption path cannot reliably supply - Retain the recognition anchor and rationale the intended consumption path cannot reliably supply — an enforced path can carry the anchor itself; reconstructable framework recap factors into the linked artifact, tested by downstream effects
• A note is an atomic step relative to the check that reads it - Two independent bounds on a note: one claim sized to the reader's bounded context, and one checkable inference sized to the checker's single pass — for the grounding check the unit is the unquoted source
• 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
• Alexander's patterns connect to knowledge system design at multiple levels - Maps Alexander's Context/Problem/Forces/Solution pattern to typed document contracts and his generative process to incremental codification, while marking the looser 'centers' analogy
• An adversarial human-agent loop can reconstruct the writing-is-thinking filter - The writing-is-thinking filter is the loop's, not the pen's — an adversarial human-agent loop can reconstruct what naive delegation loses, but only while the human stays the judge
• 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
• Answerability - Definition — an artifact is answerable when its collection contract can name what it answers to, the correctness or currency property asserted, and the discrepancy that triggers correction
• 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.
• Attempted recovery identifies informational gaps, not provenance or authority - Recovery failure shows content is missing from the tested source; causal provenance and live authority require independent evidence, and only pairs with unique content on both sides are bidirectionally irrecoverable
• 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.
• Claim notes should use Toulmin-derived sections for structured argument - Three independent threads converged on Toulmin's argument structure — adopting Toulmin sections as base type structured-claim separates claim-titled notes (any note) from fully argued claims (the type)
• 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.
• Directory-scoped types are cheaper than global types - Globally eligible types widen every collection's authoring choices; collection-local types keep specialized contracts scoped while path pointers load either kind on demand
• Document types should be verifiable - Document types should assert verifiable structural properties, not subject matter — with a base type + traits model inspired by gradual and structural typing
• First-principles reasoning selects for explanatory-reach over adaptive fit - First-principles reasoning selects explanations with explanatory-reach, accountable to observed fit, premise variation, and rival-practice tests
• Full write briefs cut edit drift; one-line briefs did not - Pre-registered pilot, 95 edit runs on 10 KB documents: a full retained write brief cut dropped commission items by about two thirds, a brief rebuilt from the commissioned document did nearly as well, and a one-line brief matched no brief
• Load-bearing vocabulary collisions should be prevented or visibly scoped at write time - Unqualified technical senses have no reliable namespace in natural-language content; schema slots, rare compounds, and linked clause frames scope them at write time; audits and remediation recover when prevention fails
• Mixed epistemic status must be preserved below the document level - A document can combine observations, deductions, and plausible explanations; KB writing and review must retain which claims and transitions have which warrant.
• Naur's compiler case tests one historically bounded documentation-and-consumption system - Naur's compiler transfer failure rules out more documentation of the same kind, but tested one historically bounded package and consumption process rather than every possible rationale, indexing, retrieval, and activation system
• Process structure and output structure are independent levers - Distinguishes constraints on reasoning steps from constraints on result shape and identifies the evidence needed to separate their effects
• Repair dispositions for defeated claims are an epistemic policy with an option space - Proposal: the undecided remainder of repair-policy design after ADR 066 — declaring repair policy in an installation's local collection contract, and freshness-store drift tracking for idealization pricing attestations
• Reverse compression is when LLM output expands without adding information - LLMs can inflate compact seeds into verbose artifacts without adding extractable structure; a KB resists this only when links make additional structure accessible
• Semantic review catches content errors that structural validation cannot - Structural validation catches form errors; semantic review catches content errors like incomplete enumerations, grounding drift, boundary-case gaps, and internal contradictions
• Seven documentation cases left routing and synthesis - A seven-artifact Commonplace sweep found that direct source access removed exact-fact prose while discovery maps and cross-component boundaries survived; it does not establish a universal documentation ratio
• Short composable notes maximize combinatorial discovery - The library's purpose is to produce notes that can be co-loaded for combinatorial discovery — short atomic notes are a consequence of this goal; longer synthesized artifacts belong in workshops or derived instructions
• Structured output is easier for humans to review - Separated Evidence and Reasoning sections let human reviewers check facts and logic independently — a purely readability argument that doesn't depend on LLM behavior at all
• Structured-prompt gains do not establish training-distribution selection - Formatting compliance, extra computation, and task decomposition can mimic distribution-selection gains, so prompt performance alone cannot identify the mechanism
• 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
• The wikiwiki principle: lowest-friction capture, then progressive refinement in place - Ward Cunningham's wiki design principle — minimize capture friction, refine in place — drives the text→note→structured-claim codification ladder
• 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
• Title as claim exposes commitments, enabling Popperian maintenance - When an index is a list of claims rather than topics, reviewing the KB becomes scanning hypotheses — each title exposes its commitment and invites the question "do I still believe this?" without opening the file
• Title as claim makes overlap between notes visible - When note titles are claims, overlap between notes is visible at the index level — similar assertions are obvious without opening files; topical titles hide overlap behind different labels for the same territory
• 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
• Type system enforces metadata that navigation depends on - Descriptions don't appear spontaneously — they exist because the note base type requires them; without enforcement, metadata degrades and navigation collapses to opening every document
• Types give agents structural hints before opening documents - Types and descriptions let agents make routing decisions without loading full documents — the type says what operations a document affords, the description filters among instances of that type
• Verification needs a typed target before it needs an oracle - A check's warrant depends on a declared target class, so an unverifiable heterogeneous layer is usually blocked by missing artifact classification, not oracle difficulty — ontology precedes oracle
• Warranted reader update is the objective of substantive writing - Defines epistemic interestingness as a relevant, warranted change relative to an intended reader's prior, making contribution selection—not accumulated inputs—the purpose of multistage writing.
• Why notes have types - Seven roles of the type system — navigation hints, metadata enforcement, verifiable structure, local extensibility, content-layer identification, output quality through structured writing discipline, and maturation through constraining