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 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
• 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
• 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
• 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
• 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.
• 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
• Model partition registry - Proposal: introduce a model partition registry for review validation, aliases, and runner defaults without making the registry the review identity
• 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.
• 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.
• 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