Authoritative reference for the dx language. Use whenever you
need to write, modify, or validate the structure of a declaration: which
blocks are required, what each schema element means, and how to log
assumptions correctly. Load this any time you are about to emit
Markdown into a `.md` declaration or answer a spec-conformance
question.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Authoritative reference for the dx language. Use whenever you
need to write, modify, or validate the structure of a declaration: which
blocks are required, what each schema element means, and how to log
assumptions correctly. Load this any time you are about to emit
Markdown into a `.md` declaration or answer a spec-conformance
question.
Authoring Declarations
This skill is the working reference for the dx language. The normative
source is SPECIFICATION.md at the repo root; this document is a
denser, more prescriptive version meant to be read by an agent before
each emission.
Why the two-tier grammar matters. The structural layer (heading
levels 1–3 plus the Given/When/Then bold convention) is enforced
mechanically by the linter. Everything between two structural headings
is opaque Markdown leaf content: ordinary prose, inline code,
links, tables, fenced code blocks, even ####+ headings for prose
sub-structure. The leaf layer is not interpreted by the toolchain.
When prose contains characters Markdown interprets (asterisks,
underscores, backticks, square brackets), escape them per standard
Markdown rules.
The slug rule. Each ### heading body is human prose
(e.g., ### Single line on stdout). The toolchain reduces every
heading body to a slug for AST keys, diff stability, and any
shell-script consumer: lowercase, ASCII alphanumerics preserved,
runs of other characters collapsed to a single underscore,
leading/trailing underscores trimmed. Single line on stdout
reduces to single_line_on_stdout. Two headings within the same
block that reduce to the same slug are a structural error.
2. Required vs. Optional Blocks
Block
Required
Empty allowed?
Notes
# <system>
Yes
No
Short phrase in heading body.
## Intent
Yes
No (the body MUST be a paragraph or a list)
One sentence or a priority list.
## Invariants
Yes
Yes (heading with zero ### children)
Heading itself must exist.
## Assumptions
Yes
Yes (heading with zero ### children, semantically meaningful)
Heading itself must exist.
## Contracts
No
—
Add as soon as a contract is real.
## Unconstrained
No
—
Use to prevent over-specification.
Note: even when there are no invariants or assumptions, the ##heading must be present. The linter distinguishes "intentionally
empty" (heading present, no ### children) from "forgot to write it
down" (heading missing entirely).
3. Block-by-Block Schema
3a. # <system>
The # level-1 heading body is the system name. A short phrase;
conventionally kebab-case (# hello-world) but a human-readable
form (# Hello World) is also valid. Treat as the namespace for
this declaration.
# hello-world
3b. ## Intent
The body of ## Intent is either a single Markdown paragraph
or an unordered list (priority order, most important first).
Choose one form; mixing them is a structural error.
A single-sentence intent:
## Intent
Greet a user by name on standard output.
Or a priority list (when more than one intent matters):
## Intent- Greet a user by name on standard output.
- Be friendly.
- Exit cleanly.
Each item is a goal, not a task. "Be fast" is fine; "use a
thread pool" is not — that's implementation, and belongs nowhere
in a declaration.
3c. ## Invariants
A block of ### key sections. Each heading body is free-form
prose naming the invariant; the content under the heading is the
invariant body.
## Invariants### Single line on stdout
Writes a single UTF-8 line to stdout terminated by `\n`.
### Cold-start latency
Cold-start latency must remain under 50ms on commodity hardware.
### No network access
The implementation must not open any network sockets.
Multi-paragraph bodies are fine; they read as ordinary
Markdown:
### Complex rule
The first paragraph states the rule.
A subsequent paragraph elaborates with examples or edge cases.
Where useful, leaf prose may include a fenced code block to pin
observable output exactly:
` ` `
expected stdout line one
expected stdout line two
` ` `
Category convention (SHOULD). When grouping a long list of
invariants by concern, prefix the heading with the category
followed by a colon: ### Interface: single line on stdout,
### Performance: cold-start latency, ### Security: no network access. The resulting slugs (interface_single_line_on_stdout,
etc.) are scannable in tool output and group together
alphabetically. Conventional categories: Interface,
Performance, Security, Observability, Data, User experience. Invent new ones as needed but stay consistent within
a single declaration.
Each invariant is a black-box statement. It describes
observable system behavior, never internal architecture. "Uses a
Bloom filter" is not an invariant; "membership queries return
false-negative rate of 0" is.
3d. ## Assumptions
The most important block in the system. Same shape as Invariants.
## Assumptions### Default output format
When neither `--json` nor `--text` is passed, the CLI defaults
to human-readable text. The spec does not pin the default, and
the original C++ implementation defaulted to text; preserving
that minimizes surprise for existing users of the legacy tool.
An assumption is a heuristic choice the agent had to make
because the human's intent + invariants did not uniquely
determine the answer. Every assumption entry must include what
was decided and why. The architect later promotes (move to
## Invariants) or rejects (rewrite the code and delete the
entry) each one.
An empty ## Assumptions block (heading with zero ###
children) is a meaningful state: it asserts "I made no
unrecorded heuristic choices." Use it deliberately.
Multi-implementation namespace convention. When a single
declaration governs multiple implementations (e.g.,
impl_python/, impl_cpp/, impl_go/), each implementation
necessarily makes its own per-language choices: which Markdown
library, which HTTP server, which JSON parser. Convention is
to namespace the assumption heading with the implementation
identifier as a leading word, e.g.:
### python.markdown_flavor
The Python implementation uses the `markdown` package with
fenced_code, tables, and attr_list extensions to approximate
GitHub Flavored Markdown.
### cpp.markdown_implementation
The C++ implementation uses md4c with the GFM HTML renderer.
The slug-reduction rule turns these into python_markdown_flavor
and cpp_markdown_implementation, which sort together by
prefix in dx contracts list and dx diff output. The
architect's later triage pass should look at each pair of
namespaced assumptions and ask whether the divergence is
something the spec should care about (promote to an invariant
that constrains every implementation, demote to
## Unconstrained because no observable outcome depends on
it, or leave as parallel assumptions because each implementation
genuinely needs to make this choice locally).
3e. ## Contracts
Black-box verification rules in given/when/then form. The three
sub-fields are introduced by paragraph-leading bold markers
exactly: **Given**, **When**, **Then**.
## Contracts### Greets a named user**Given** the argument vector contains exactly one non-empty name.
**When** the binary is invoked.
**Then** stdout contains `Hello, <name>!\n` and the exit code is 0.
All three sub-fields are REQUIRED per contract; a missing
sub-field is a lint error.
The body of a sub-field is the paragraph that begins with the
bold marker, plus any subsequent paragraphs up to the next
recognized marker or heading.
**Then** clauses must be observable (stdout, exit code,
file state, HTTP response, …). Never reference internal state.
One contract = one observable outcome. If you need
conjunctions, prefer multiple contracts.
3f. ## Unconstrained
A block of ### key sections; each heading body names the
degree of freedom, and the content under the heading is the
description of what was granted.
## Unconstrained### Implementation language
Any language with a stable POSIX runtime is acceptable.
### Storage backend
Choose any durable key-value store; SQLite is acceptable.
If you find yourself wanting to write "we don't care about X," X
belongs here — not in Invariants, not in a comment.
4. The Assumption-Logging Protocol (AGENTS.md §2)
Whenever you (the agent) face a choice not specified by
## Intent or ## Invariants:
Stop before emitting. Do not write the choice into code or
prose until step 4 is done.
Pick a heading. Use prose that names the choice
(e.g., ### Default output format). The toolchain will
reduce it to a stable slug (default_output_format).
Write the entry in ## Assumptions as a ### <heading>
section. The body must answer: what did you decide and
why was that the most defensible choice given the
ambiguity.
Then proceed with implementation.
Anti-pattern to avoid: appending the assumption after the
implementation is written. The whole point is that the
assumption is recorded before the heuristic leaks into code.
5. Pruning Heuristic (AGENTS.md §4)
Before adding any new invariant, ask:
Could the human's stated intent be satisfied without this
constraint?
Is this a requirement of the system, or a preference of mine?
Would relaxing this invariant change anything observable?
If any answer suggests the constraint isn't truly required, move
it to ## Unconstrained (with a description) or omit it
entirely.
6. Self-Validation Checklist
Before considering a declaration write complete:
dx lint <file>.md exits 0.
Exactly one # heading, first in the document, with a
non-empty body.
Every ## heading body is one of: Intent, Invariants,
Assumptions, Contracts, Unconstrained.
No ## heading appears more than once.
Every ### key sits inside a recognized ## block (and
not inside ## Intent).
## Intent has a non-empty body (a paragraph or a list).
No two ### headings in the same block reduce to the
same slug.
Every contract has all three of **Given**, **When**,
**Then**, each appearing at most once.
Every invariant is a black-box statement (no
implementation details).
Every contract **Then** clause is observable.
Every assumption has a why, not just a what.
Anything the human didn't constrain lives in
## Unconstrained or not at all.
7. Worked Example
A minimal but complete declaration demonstrating every block:
# hello-world## Intent- Greet a user by name on standard output.
- Be friendly.
- Exit cleanly.
## Invariants### Single line on stdout
Writes a single UTF-8 line to stdout terminated by `\n`.
### Cold-start latency
Cold-start latency must remain under 50ms on commodity hardware.
## Assumptions### Greeting format
The greeting is "Hello, <name>!" — the spec does not pin the
punctuation or word choice, and this matches the canonical
POSIX-tutorial form.
## Contracts### Greets a named user**Given** the argument vector contains exactly one non-empty name.
**When** the binary is invoked.
**Then** stdout contains `Hello, <name>!\n` and the exit code is 0.
## Unconstrained### Implementation language
Any language with a stable POSIX runtime is acceptable.
