Conventions¶
How to write in this vault: the note types, the status lifecycle, and the handful of rules that make the vault's views work. Four minutes to read — read it before your first note.
Every note declares its type¶
One frontmatter field powers every view in the vault:
type |
What it is | Lives in |
|---|---|---|
moc |
A hub that links rather than explains | anywhere |
kb |
An explainer — how to, why we, what is | 05-project/, 90-meta/ |
design |
A proposal for something not yet built | 10-design/ |
system |
A spec describing something that exists | 10-design/ |
decision |
An ADR | 30-decisions/ |
epic |
A container for related tickets | 50-work/ |
ticket |
One unit of assignable work | 50-work/ |
board |
A Kanban board — a view, not a source of truth | 50-work/ |
question |
An unresolved thing that blocks work | 90-meta/ |
person |
A teammate | 90-meta/ |
meeting |
Notes from a meeting | 90-meta/ |
runbook |
A procedure followed under pressure | 60-ops/ |
A note with no type is invisible to every view, and nothing will tell you — it simply will not
appear.
The status lifecycle¶
Most of what a young project writes describes something that does not exist yet, which is why this is the table that matters most:
| Status | Means | You may |
|---|---|---|
draft |
Being written | Read it and comment, but do not rely on it |
review |
Under team review | Comment |
agreed |
We have committed to building this | Write tickets against it |
current |
This describes what actually exists, verified | Rely on it |
superseded |
Replaced — links to its successor | Read for history only |
agreed is not current
agreed means build this. current means this is what exists. A note that jumps to
current before the code lands is a lie the team will trip over in month three.
status is the first thing to read on any note. It is how you tell a description of the world
from a plan for it.
Status means different things in different families¶
Four kinds of note use four different value sets, and the views are built on exactly these. A value outside its set is invisible to the views rather than an error — so a typo looks exactly like an empty list:
| Family | Values |
|---|---|
Documentation (kb, moc, design, system, runbook) |
the lifecycle above |
Decisions (decision) |
proposed → accepted or rejected |
Work (ticket) |
backlog, todo, in-progress, blocked, review, done |
Questions (question) |
open, closed |
An ADR is never draft or agreed: it is proposed while the team is deciding, then accepted or
rejected.
Frontmatter¶
---
type: design
title: <title>
status: draft
owner: "[[people/<name>]]"
updated: 2026-09-17
tags: []
---
Quote links in frontmatter — owner: "[[people/phil]]". Unquoted, a strict YAML parser reads it as a
nested list.
Linking¶
- Link by note name, never by path. The editor rewrites links on rename; paths rot.
- Say what the link is for — don't drop it at the end of a sentence.
- Every note should be reachable from a hub within two links. An orphan is a note nobody finds.
- Embed a fact rather than restating it, so there is one place to fix it.
Naming¶
ADR-0003 — Use component nodes, TICKET-042 — Add coyote time. Prefix, em dash, title. Never
rename a ticket — its ID is referenced from boards and from commit messages.
Callouts¶
Same meaning, same type, everywhere:
| Type | For |
|---|---|
abstract |
The summary at the top of every note |
info |
Context |
tip |
Something that saves real time |
warning |
A gotcha that will cost an hour |
danger |
Destructive or irreversible |
question |
An open question with an owner |
todo |
An action item with an owner |
success |
Verified |
Two or three per note. If everything is highlighted, nothing is.
Conflict copies¶
Sharing is per folder. When two versions of a note cannot be merged, the sync writes
<name> (relay conflict <timestamp>).md beside the original — and it is not an artefact to ignore.
The vault now holds two divergent answers to one question, and both are valid notes that nothing
flags.
- Diff the copy against the original — both are plain files.
- Decide per hunk. The live file is often a superset, but check rather than assume.
- Move anything unique into the original.
- Delete the copy. Keeping it means the wrong answer gets cited eventually.
Never rewrite a whole shared note programmatically, and never rewrite a board file: merges of concurrent edits are silent, so a bad one leaves no marker behind.
Next: How we work