Decisions
Every architectural decision, what was measured to reach it, and what would make us revisit it.
Each of these looks arbitrary until you know why. Changing one is fine; doing it without reading the reason is not.
Every record follows the same shape: the context with the numbers that produced it, the options weighed, the decision, and — the part that matters most — what would make us reverse it.
| Decision | The measurement behind it | |
|---|---|---|
| 001 | TypeScript on Node | An empty Node process costs 40 ms of a 200 ms budget |
| 002 | JSON, one object per file | JSON parses 10k events in 6 ms; YAML takes 496 ms |
| 003 | No runtime dependencies in the core | zod costs 23.6 ms to import — 15% of the budget for a seven-field object |
| 004 | cac for arguments, esbuild for the bundle | cac imports in 3.3 ms against 17.1 ms for commander |
| 005 | Synchronous I/O, mandatory snapshot | Async reading measured 42 ms slower; the snapshot is 23× faster |
| 006 | Keep cac, load the TUI lazily | blessed costs 28 ms; the fast path must never pay for it |
| 007 | The repository is the product | 80% of tracked files had nothing to do with kadence |
| 008 | The site lives in its own repository | A landing page cannot pass the ADR-007 test |
| 009 | The agent contract: both entry files, coded errors, a published schema | Claude Code loads CLAUDE.md and does not read AGENTS.md |
| 010 | Decisions are events; documents are linked, not stored | A grep buries the answering document among 10–35 candidates — 1.3 MB against 39 KB |
The canonical records are in the product repository's journal, as documents:
kadence doc list in a clone, and every decision since, with its reason
and the alternatives that lost, in kadence decision list.
The first eight were written in Ukrainian and the pages here are translations;
from ADR-009 the records are written in English and these are copies. If the two
ever disagree, the repository wins.