Design docs
Every non-trivial change starts with a design conversation. Without a
home, it lands in a wiki, a gist, a chat scrollback: a hairy pile of
documents no tool reads and no gate keeps honest. Design docs give
that conversation one format, one directory (cohere/design/), and a
lifecycle the tooling enforces.
Anatomy
A design doc is frontmatter (design, status: draft | accepted |
superseded, date, contexts, optionally supersedes) plus
sections: Problem, Existing ground, Shape, Promised surface,
Decisions, Open questions, Status log.
Existing ground
Assembled by mix cohere.design when the doc is born: each anchored
context's current API from the map, plus the invariants and decisions
from its intent card, inlined as a dated snapshot. Constraints
nobody opens don't constrain anything, so the constraints are
delivered onto the page where the designing happens. A design is a
dated record; quoting the ground as-of its date is a quote in a
meeting record, not a second truth.
Promised surface
The backticked refs the design commits to delivering. This is what
makes a design doc a mechanically checkable spec instead of
aspirational prose: mix cohere.complete fails until every promised
ref resolves in the compiled app. Promise MyApp.Deals.reverse_deal/1
and the design cannot land without it.
Lifecycle
- Draft. Work in flight. The draft is the in-flight state; there is no dotfile, no registry. Check reads status fresh from disk.
- Accepted.
mix cohere.completeverified the promises, flipped the status, dated the log. Accepted designs are immutable history. - Superseded. New thinking is a new doc naming the old slug in
its
supersedes:frontmatter. History is superseded, never edited.
Advisory by construction
Design findings never fail the build; only the map and cards can exit 1. A design that has drifted from today's code is history doing its job: drift on intent is a bug, drift on history is information.
Completing a design forces the anchored cards through re-review, and that is the moment the design's durable decisions get distilled into intent cards. Cards cite designs by slug, so the trail stays walkable in both directions.