KB maintenance

Type: types/tag-readme.md

How an agent-operated knowledge base stays healthy as it grows: the checks that catch errors, the discipline that keeps claims supportable, and the curation that keeps the library navigable. Three child areas carry most of it. Nearby but different: observability is about making hidden state and drift visible; maintenance is what acts on it. For how the KB is built rather than kept, see architecture and document-system.

Child areas

• review-system — the review pipeline: gates and criteria, verdicts and outcomes, freshness baselines, the review protocol, its cost evidence, and the proposals that would extend it
• claims-and-grounding — claims as units and what supports them: title as claim, claim modality, quotes and source grounding, what creates ground truth, what a superseded belief keeps
• curation — keeping the library navigable: indexes and tag heads, quality signals and scores, periodic hygiene, maintenance capacity, retirement

Across the children

• Attempted recovery identifies informational gaps, not provenance or authority — what regenerating a system from its documentation does and does not show
• Seven documentation cases left routing and synthesis — a bounded sweep: direct source access removed exact-fact prose, checked discovery kept routing and synthesis
• Final task success does not establish intended-path health — identical terminal outcomes can hide a broken prescribed path; maintenance needs path evidence
• Domain pricing routes an exception to idealization assessment but does not decide it — truth verdicts separated from repair dispositions
• Brainstorming: how explanatory-reach informs KB design — working notes on what the quality goal implies for maintenance choices
• A reader-facing banner for user verification — proposal: show verification status to readers of the published site

Related Tags

• observability — the signals maintenance acts on
• document-system — the type system and validation that maintenance checks against
• links — the linking methodology staleness detection and quality signals operate on

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 derived copy of recomputable truth must be checked or absent - When an artifact carries a copy of information recomputable from a ground-truth source, the copy must be machine-checked against that source or not exist — hand-maintained-and-trusted is forbidden
• A five-link cap missed four grounding findings in twelve reviews - A paired Commonplace assay found five capped-versus-uncapped grounding outcome divergences; one reproduced as reviewer noise, while four appeared only after fuller reading reached 6–16 linked artifacts
• A linked note discharges its own grounding, so a citing note owes representation, not re-grounding - A cited source imposes a grounding obligation; a claim-titled note that already passed its own grounding review imposes only a representation obligation — with the preconditions that keep the distinction and why it is not a paraphrase ledger
• 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 quotes-route rollout grounded more claim uses without earning claim identifiers - A Commonplace grounding rollout recorded 30% grounded claim uses under a paraphrased claims ledger and 75% under verbatim quotes or pinned snapshots, with no case needing claim identifiers; the non-random cohorts make the gap descriptive
• A retrieval miss is a local reflective-path failure - A missed relevant artifact leaves its represented aspect inert for the affected task and discovery route, while other loading paths and reflective aspects can remain causally connected
• Ad hoc explanation can be rational when error is cheap and local - Explains why a disposable local guess can rationally select the next probe when error is cheap and contained, while retained explanations need reach checks
• 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 independent pass tightened three of four Pirolli grounding verdicts - A Commonplace grounding case changed three of four support verdicts after separating source reconstruction from target-claim judgment, making bilateral isolation a candidate control rather than a proven cause.
• Automated note refinement as a search over a fixed source bundle - Proposal: build the automated note-refinement loop on a source bundle that emits a set of notes, not a single identity-stable note — reframing non-convergence (split, drift, kill) as search outcomes
• Calibrating semantic gates against labelled fixtures - Proposal: require non-leaking known-case regression before a semantic gate can advance, and reserve live detection-rate claims for separately sampled field calibration
• 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 modality is the inference form of the refuter - The three claim modes are refuter-defined images of deduction, induction, and comparative abduction; grounds the mode list's closure for empirical claims and gives vacuity and genre drift precise readings
• Collection-as-artifact freshness - Proposal: register collection-maintenance targets with collection-text inputs for casebook-wide staleness without per-file dependency edges
• Commitment, not derivation, creates new ground truth - Derivation — claims recoverable from the source, nothing added — leaves the source as ground truth; what adds unentailed resolutions becomes ground truth at commit, repaired by supersession
• Criteria edits invalidate verdicts; process edits invalidate artifacts - Editing quality criteria invalidates verdicts; editing production processes calls for artifact regeneration — verdict freshness includes the artifact and criteria but excludes its production process
• Decorrelated reviewers still share the field's prior, so read their findings by the claim's stance - Decorrelating reviewers removes the author's errors, not the field's; judges converge on consensus where a claim is original, so findings are read by stance and as reconnaissance: engage where load-bearing, deflect where not
• Factored dependency pairs for review freshness - Proposal: keep review dependencies factored as two-input pairs where that shape fits; type and collection pairs and cohort ack are shipped while a review target with more than two inputs remains
• Full improvement pass closure - How the shipped full-improvement workflow reassays final note bytes, routes residual findings, and stops without claiming convergence
• Gate learning from accepted edits - Proposal: learn review gates from accepted note edits, with candidate mining, usefulness tracking, lifecycle promotion, and budgeted loading. Atomic gates shipped; learning has not
• 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
• Generalized validation invalidation and imperative extension - Proposal: generalize validator invalidation or imperative type extension only after explicit selectors and local mark cases prove reusable machinery
• History has one chance to become checkable - An artifact's production history is convertible to later-checkable form only at production time, via records/attestation or re-derivability; after that a bounded reviewer sees only carried state
• Index completeness does not determine editorial orientation - Complete generated listings establish membership, but their inputs do not determine topic-specific grouping, role phrases, or reading order without editorial judgment
• Indexes lower recall when they suppress retrieval that would find more - A plausibly exhaustive index lowers route-level recall only when it prevents retrieval that would have produced greater task-relevant coverage
• Keyword tags without heads - Proposal: a second, weaker kind of tag — a keyword with no head, no page, and no marks, for scoped search only — declared per collection; set aside by ADR 089 on YAGNI grounds until search-only tagging shows a need
• Link graph plus timestamps enables make-like staleness detection - Existing links already encode dependency information; comparing note and target timestamps flags notes that may be stale without any new annotation, analogous to make's file-based rebuild logic.
• Link strength is encoded in position and prose - Not all links are equal — inline premise links ("since [X]") carry more weight than footer "related" links. Position and prose encode commitment level, creating a weighted graph that affects traversal, scoring, and quality signals.
• Maintenance capacity must match harmful-artifact inflow - Stable quality depends on capacity to prevent, contain, detect, and repair harmful retained artifacts keeping pace with their risk-weighted inflow, for which gross generation volume is only a proxy
• Maintenance operations catalogue should stage stable procedures for instructions - Catalogue of periodic KB maintenance operations and readiness status, used as a staging ground before promotion into kb/instructions procedures
• 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.
• Model partition registry - Proposal: introduce a model partition registry for review validation, aliases, and runner defaults without making the registry the review identity
• 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.
• Notes need quality scores to scale curation - As the KB grows, /connect will retrieve too many candidates — evidence, type, inbound links, recency, and link strength can rank what is worth evaluating
• Periodic connect-report mining - Proposal: mine connect reports on a recurring cadence as a bulk-operation pipeline, automating the noticing-to-candidate triage step connect and kb/log.md leave unattended
• Periodic KB hygiene should be externally triggered, not embedded in routing - Routing instructions serve the current task; periodic hygiene is triggered externally (user, heartbeat, CI), so embedding it in always-loaded routing blurs two responsibilities and adds session noise
• Quality signals for KB evaluation - Catalogues graph-topology, content-proxy, and LLM-hybrid signals that could be combined into a weak composite oracle to drive a mutation-based KB learning loop without requiring usage data.
• Reasoning production is not reasoning evaluation - Review and critique systems need independent process-validity checks because a model can substitute answer reconstruction for reasoning evaluation
• Review automation should target verifiable subroles before reviewer identity - Scholarly-review automation should decompose reviewer work into separately verifiable subroles before giving an AI system reviewer-level authority
• Review configuration object - Proposal: give commonplace.review a ReviewConfig for review scan roots, gate and artifact locations, and database path with project overrides, without introducing a global ProjectConfig
• Routine bilateral isolation for literature assessment - Proposal: decide whether prospective matched evidence should promote bilateral isolation from a conditional diagnostic to a routine literature-assessment control
• 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
• Single-artifact review bundles still cut Claude costs substantially after cache-aware weighting - April 2-4, 2026 review telemetry reweighted with Anthropic Opus 4.6 prompt-caching prices still shows a substantial cost drop from the single-artifact bundle refactor
• Structured-output codec for the review protocol - Proposal: make review output a pluggable codec, with sentinel markdown today and schema-validated structured output when harnesses expose it
• Superseded choices need a historical witness; refuted beliefs lose subject-matter standing - Retention after supersession follows remaining truth role rather than maintenance operation: preserve a witness to the choice event, while a refuted belief loses subject-matter standing
• Tag maintenance and derived browsing - Proposal: test temporary topic groupings and reviewed tag-maintenance suggestions before changing Commonplace’s canonical tag structure.
• Theory warrant should be tracked at the finest granularity evidence licenses - Treat support for a theory as warrant for only the most specific claim, conjunction, model, and scope the evidence identifies; do not distribute joint warrant beyond what it entails without additional attribution
• Title as claim enables traversal as reasoning - When note titles are claims rather than topics, following links between them reads as a chain of reasoning — the file tree becomes a scan of arguments, and link semantics (since, because, but) encode relationship types
• 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
• Traversal improvements should be deferred via logging to avoid mid-task context switching - Loading writing methodology into an already-committed context window is expensive; a one-line log entry preserves the improvement signal at near-zero cost and lets a separate pass do the fix
• Write-time vocabulary collision controls - Proposal: mechanical controls for the one-term-one-sense invariant — reserved-term registry, slot-escape lint, coinage collision screen, naming-review gate, and clausal-binding link check