LLM Best Practices

Linking and Tags

4 min read

View markdown source

Overview

A vault’s value is in its edges, not its nodes. Two rules govern them: relationships are always wikilinks, and tags carry state rather than meaning. Mixing the two produces a vault where nothing is navigable and every tag is a folder nobody can query. The note-level link budget is in atomic-notes.

If you want to tag a note #interesting, what you actually want is a link from the note that finds it interesting. A tag is a flat string that carries no direction and no reason; a link is directional, resolvable, and carries a backlink.

  • Relationships between ideas: [[wikilink]], always.
  • Note state: a status tag, exactly one per note.
  • Domain membership: a nested domain tag, several allowed.
tags: ["status/budding", "domain/finance/macro", "domain/realestate/leasing"]

Free-floating descriptive tags are banned. #important, #todo, and #interesting accumulate until the tag pane is unusable and no query can rely on any of them.

A link with no sentence around it records that two notes are adjacent without recording why. Six months later the reason is gone, and the edge is decoration.

Good: The decomposition holds only when the branches are exhaustive, which is
the failure mode described in [[mece-issue-tree|MECE decomposition]].
 
Bad:  ## Related
      [[mece-issue-tree]]
      [[pyramid-principle]]
      [[issue-tree-depth]]

A trailing list of bare links at the bottom of a note is the naked link dump, and it is the single most common way a vault looks well-connected while carrying no reasoning. Auditors flag runs of consecutive bare-link bullets for exactly this reason. See vault-audit.

Kebab-case claim filenames are precise and unreadable inline. Alias them.

The central insight in [[compound-interest-doubles-money-faster-than-linear-saving|compounding]]
is that the doubling time, not the rate, is what the saver controls.

The link target stays canonical, the sentence stays readable, and renaming the target updates the link without touching the prose. Filenames follow the kebab-case rule in naming-conventions.

Cite specific paragraphs with block references

When an atom rests on one passage of a source, link the passage, not the whole document. Block references make the citation checkable.

The 70-book figure comes from [[@schmidt-2018-luhmann-archive#^p-23|^p-23]].
Timestamped media uses the same pattern: [[@lex-2024-episode#^t-42-15|^t-42-15]].

Use ^p-23 for page 23 and ^t-42-15 for timestamp 42:15. The convention matters less than picking one and holding it. Sourcing discipline is covered in source-verification.

Grow maps of content from clusters, never pre-build them

A Map of Content is a note that indexes a cluster of atoms with a sentence of context each. Create one only when at least four tightly related atoms already exist. A MOC built before its atoms is an empty outline that shapes future notes to fit it, which is the opposite of the intent.

The trigger for a new MOC is a cluster you notice in the weekly review or one an agent surfaces from atom titles. The trigger for splitting a MOC is scale: past roughly 50 indexed atoms, or past the point where several people edit it weekly, split it into sub-MOCs. Both moves are covered in vault-maintenance.

Treat orphans as a weekly gate, not a background condition

An atom with no inbound and no outbound links is invisible: it will never surface when it is relevant, so it does not exist in practice. Orphans are a hygiene gate with two outcomes, link it or delete it, and no third option.

Clusters of orphans on one theme are a different finding: several unlinked notes about the same subject usually mean a missing MOC, not several missing links. Triage by cluster rather than one note at a time.

Backlinks