Design docs: the authored artifact of the feature loop.
A design doc records the conversation that shapes a change — problem,
existing ground, shape, promised surface, decisions with their rejected
alternatives. Docs live in cohere/design/*.md, are born draft by
mix cohere.design, and are flipped to accepted by
mix cohere.complete once every promised ref exists in the compiled
app. Accepted designs are immutable history: supersede them, never edit
them.
Designs are deliberately weaker-bound than intent cards. A card is a
living constraint set, hash-bound to a surface, and drift on it fails
the build. A design is a dated record; drift against it warns and never
fails (DEC-FEA-002 in cohere/design/feature-loop.md).
Summary
Functions
Flips a draft's status to accepted and appends a dated Status log line.
The date: frontmatter keeps the design date; the log carries the
acceptance date.
Filters docs to those whose contexts: anchors resolve to the given map
group — the packet's design slice, using the same anchor resolution as
check (Cohere.Map.fetch_group/2), not a second matcher.
Conventional design doc filename for a slug.
Renders the Existing ground for a set of context names: each anchored context's current API from the map, plus the invariants and decisions from its intent card when one exists. Names that resolve to nothing are rendered as proposed — a design may introduce the context it anchors to.
Soft findings for a design doc — never build-failing (DEC-FEA-002)
Loads every design doc in the project's design directory.
The comment-stripped content of the Open questions section, or nil when it holds nothing but skeleton prompts. Open questions warn at completion and never block (DEC-FEA-007).
Parses design doc text. Returns {:ok, %Doc{}} or {:error, reason}.
The refs promised in the ## Promised surface section, parsed without
a namespace filter — a promise is explicit, so anything promised is
checked, mix tasks included.
Generates a draft design doc skeleton.
Promised refs that do not (yet) resolve in the compiled app.
Functions
Flips a draft's status to accepted and appends a dated Status log line.
The date: frontmatter keeps the design date; the log carries the
acceptance date.
@spec anchored_to([Cohere.Design.Doc.t()], Cohere.Map.t(), map()) :: [ Cohere.Design.Doc.t() ]
Filters docs to those whose contexts: anchors resolve to the given map
group — the packet's design slice, using the same anchor resolution as
check (Cohere.Map.fetch_group/2), not a second matcher.
Superseded docs never match: the superseding doc carries the thread
(DEC-PAC-003 in cohere/design/packet-sources.md).
Conventional design doc filename for a slug.
Renders the Existing ground for a set of context names: each anchored context's current API from the map, plus the invariants and decisions from its intent card when one exists. Names that resolve to nothing are rendered as proposed — a design may introduce the context it anchors to.
Soft findings for a design doc — never build-failing (DEC-FEA-002):
{:anchor_missing, name}— an anchored context isn't in the map (fine for a draft that introduces it;mix cohere.completeverifies){:broken_ref, ref}— a namespaced ref outside Promised surface that doesn't resolve
@spec load_all(Cohere.Project.t()) :: [Cohere.Design.Doc.t()]
Loads every design doc in the project's design directory.
The comment-stripped content of the Open questions section, or nil when it holds nothing but skeleton prompts. Open questions warn at completion and never block (DEC-FEA-007).
@spec parse(String.t(), String.t() | nil) :: {:ok, Cohere.Design.Doc.t()} | {:error, term()}
Parses design doc text. Returns {:ok, %Doc{}} or {:error, reason}.
The refs promised in the ## Promised surface section, parsed without
a namespace filter — a promise is explicit, so anything promised is
checked, mix tasks included.
Generates a draft design doc skeleton.
Options: :contexts (anchored context names for the frontmatter) and
:ground (pre-rendered Existing ground body from ground/2).
Promised refs that do not (yet) resolve in the compiled app.