Skip to content

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.

  1. Diff the copy against the original — both are plain files.
  2. Decide per hunk. The live file is often a superset, but check rather than assume.
  3. Move anything unique into the original.
  4. 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