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 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 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.
• 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.
• 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
• 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
• 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