LLM Best Practices

Vault Evolution

5 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Vaults outgrow their designs: a domain expands, a second framework becomes necessary, a note type goes dormant. The failure mode is the rebuild, which severs the link network and discards provenance. The rule is add, deprecate, migrate, never rebuild, and four moves cover every legitimate case. The structure being evolved is in vault-architecture.

Add a note type instead of repurposing one

When a new kind of note appears (an experiment, a vendor, a lesson), declare a new type. Redefining an existing one corrupts the audit meaning of every note already carrying it.

  1. Add the type to the spec with folder, filename pattern, and required fields (vault-frontmatter-schema).
  2. Add a template and schema reference, and create the folder.
  3. Run the auditor.

Required fields apply per type, so no existing note changes, and deleting the spec block reverses the move. This is the default answer to “the vault needs to track something new.”

Migrate when a field becomes required

Making an optional field required is the only move that touches existing notes: every note lacking it fails the audit as soon as the spec changes. Run it like a database migration, where it is not done until the data is (migrations).

  1. Change the spec, then take the worklist from the auditor. Add the field to the type’s required list and run the audit. Every note missing it fails C008, and the JSON report lists them. Do not build the list by hand; the auditor’s definition of “missing” is the one that will be enforced.
  2. Scope-freeze the backfill. More than a handful of notes is a bulk write: state the exact path list, state that the edit is a reversible frontmatter addition, and get sign-off (vault-audit). Prefer one honest value per note, written by someone who knows it or by a reviewed script that derives it.
  3. Never fabricate a value. Today’s date in last_verified on a claim verified two years ago makes the vault assert something false about its provenance. The same goes for a guessed confidence, an invented source, or an uncounted corroboration_count. When the honest value is unknown, leave the field empty and the finding open; an open warning is accurate (source-verification).
  4. Let autofix fill only what it can derive: id from the filename, created and modified from mtime, the default status, and structural tags. Run dry first, then apply. It stops at semantic fields on purpose.
  5. Re-run and treat the delta as proof. The missing-field count should return to zero with nothing new introduced. Keep both reports in the log.

In a shared vault the spec change and the backfill travel on one branch with the before and after audit output in the description (vault-pull-request-review).

To stop requiring a field, remove it from required and leave it in the notes. It stays valid, unenforced, and queryable; stripping it is a bulk write with no benefit.

Layer a second framework instead of forking

When the domain genuinely splits (a strategy vault starts hosting engineering decisions), declare the layered frameworks in the spec, add the second framework’s note types additively, and bridge the two with explicit link conventions. Framework rules trigger on prefixes, so they enforce only on notes that opt in. Keep the old queries and add the new framework’s to the dashboard. Selection criteria are in rigor-frameworks. Forking into a second vault loses the cross-domain links that were the reason both domains shared one.

Deprecate to the archive; never delete

Move a dormant type’s notes to 99-Archive/ (excluded from audit and graph), then remove the type from the spec. Order matters: removing the type first leaves active notes typeless and trips C015. Record why the layer was retired in one line so the next reader, often an agent, need not reverse-engineer it from an empty folder.

Scaling down is a legitimate evolution. When the maintenance budget is exceeded, retire a layer instead of adding structure (vault-maintenance).

Read the audit trend to see evolution coming

  • A folder outgrowing its design, or a map indexing about 50 atoms: split into sub-maps.
  • A violation cluster the current rules cannot express: add a custom rule (U prefix) to the spec.
  • Notes hand-shaped like a second framework: formalize with the layering move before the informal practice drifts.
  • A note type with no new notes in a quarter: a deprecation candidate.

Refuse the rebuild

A rebuild severs backlinks, which are the compounding value; resets version history, the hindsight-bias defense behind every decision note; and erases the audit log, so drift becomes invisible again. Each need a rebuild seems to serve is met by one of the four moves, additively and reversibly. If a rebuild happens anyway, carry the archive and history forward. In a shared vault every move is a pull request with the auditor as a check (team-vaults).

Backlinks