decision-log

Decision Log

A fresh session inherits what was written down and nothing else. The log carries a decision across that boundary, so it is written for the cold read: someone who was not there, searching months later, with no memory to fill the gaps. What that reader needs above all is to tell, from a scan, which entry holds what they came for.

1. Shape of the log

• One file with two layers. The entry layer is append-only: once written, an entry stays as written, and a change of mind arrives as a new entry that references the old one. The summary layer is a maintained field at the top and is overwritten as the current state changes. Reading the entries top to bottom shows how the thinking moved, which is usually the question being asked.
• Every entry opens with a fenced YAML block, directly under its heading:

  ## 2026-08-07 Dropped the write-through cache
  
  ```yaml
  type: decision
  status: closed
  tags: [architecture]
  source: docs/backlog.md
  ```
  

  Four keys, always present: type — one of decision (a choice made), amendment (a frozen scope changed, from workorder), rejection (a human turning an artifact down, from sensory-gate), correction (a human correcting the work), closeout (a task finished and reported, from honest-closeout). A value nothing produces is a value the format check spends its strictness guarding for no one. status — open if this entry leaves something for a later entry to close (a gate awaiting disposition, a decision flagged for revisit), closed if the entry is self-contained. Set once, at write time, like every other part of the entry — an entry that later gets closed is closed by a new entry pointing back at this one with a WikiLink (§4), never by editing this block. tags — free-form labels for grouping and filtering, [] if none apply. source — path from the project root to where the full detail lives, or the bare word none. A gate or a closeout entry carries extra keys beyond these four (§5) — same idea as Obsidian properties, where tags/aliases/cssclasses are the defaults and anything else you add is still a property. This block is what makes an entry parseable by machine and skimmable by human. Write it at the time — it is the one part of an entry that cannot be reconstructed afterwards.
• Not literal file frontmatter. Real YAML/Obsidian frontmatter is a file-level concept — one block, at the very top of the file. This log is one file with many entries, so what sits under each heading is a YAML-shaped fenced block, not something Obsidian's Properties panel will render specially. It is still genuine YAML: parseable with a real parser instead of an ad hoc line regex, and it carries the same four keys the frontmatter convention specifies (type/status/tags/source) so a decision that later graduates into its own note file needs no field rework, just the --- delimiters swapped in. See CASES.md if you're deciding whether to split this file into one-note-per-decision instead — that trade is real, and not the one this format makes.
• Entries point. Roughly five lines below the block: what was decided, the one-line reason, and where the full detail lives. When an entry starts growing, the content belongs in a real document and the entry belongs pointing at it.
• Update the summary layer — open items, current focus, counts — in the same edit as the entry below it. It gives the current state in one glance, and stays trustworthy for exactly as long as that pairing holds.
• Split at a threshold you set in advance — 200 KB unless you have a measured reason for another number. The point is having a line at all: file-reading tools truncate a long log silently, and a log you believe you read in full is worse than one you know you didn't. At the line, older entries move to a dated archive, the live file keeps the current period, and both the summary and the archive index are updated in the same pass.