adr

Architecture Decision Record (ADR)

"Beads on a necklace" — sequential isolated decisions that build on each other. Each decision narrows the space for the next one.

What this skill produces

Default — single file {feature}-decisions.md in the project root. This file is the source /spec cuts phases from: it records the decisions and their reasons, not the order of work. Works well for features up to ~15 decisions and ~800 lines.

The document opens with two things, before any decision: a short "How it works" (the whole mechanism in 5-10 lines, as it stands after the decisions made so far — rewritten as decisions land) and a status table (number, title, DECIDED / PENDING / DROPPED). A reader who lost the thread re-anchors here, not by scrolling the decisions.

Companion visual — the storyboard "Life of one X". The main visual of the ADR, built together with the decision tree in Phase 3 and kept alive through Phase 4 (see there). The tree is a list; the storyboard is the story the list is about — it is what makes the whole picture hold at the end instead of falling apart into sixteen items.

For larger features — split into per-decision directory docs/adr/{domain}/:

• One README.md (index + status table + reading order)
• One file per decision or per tightly-grouped decision cluster (e.g. 01-platform-install.md, 02-schema-source-of-truth.md, ..., 11-documentation-rollout.md)
• Logical grouping, not strict 1-to-1 (combine tightly related decisions into one file when they share rationale, e.g. 3 + 4 → single file; keep large independent decisions like 7 standalone)
• Cross-references via markdown links ([02-schema-source-of-truth.md](02-schema-source-of-truth.md)) instead of inline per 7 text

When to split — one scale: ~800 lines / ~25 KB or 15+ decisions. Past ~800 lines the Read tool hits its 25k-token limit on Cyrillic content and humans stop reviewing coherently; past 15 decisions the file keeps growing, so split early. Two further triggers regardless of size: unrelated domains in one ADR (DB + secrets + CI — targeted edits and smaller review passes), and a project that already uses docs/adr/{domain}/. Below the scale, stay in one file — a split adds navigation for nothing, and a prototype whose decisions will consolidate or die is not worth the carpentry.