How to Write a Spec

Specification > meta

Informative. This chapter is a guide, not a conformance target. It explains how the chapters in this specification are written, so a new chapter is consistent on the first try and a new spec in the container starts from the same shape.

A specification is the durable, testable authority for “what is the rule” — one place a human or an agent can look up the answer, version it, and grade against it. A plan is disposable; a spec is the thing the plan serves. This chapter documents the house style every other chapter already follows: the anatomy of a chapter, how normative and informative text differ, how to write rules that hold up, the Depends on / Related cross-reference rules, versioning, the one-language style, and the principle that grading lives in the spec from day one. It doubles as the authoring contract: if a new chapter passes the checklist at the end, it fits.

Why a spec, not a plan

A plan answers “what will we do next”; a spec answers “what is true regardless of the plan.” Rules that recur across projects and sessions belong in a spec, because a spec is loaded as durable operating context and is graded, while a plan is thrown away when the work ships. Write a spec when a preference is stable enough to be looked up rather than re-decided each time.

Anatomy of a chapter

Every chapter follows the same skeleton, and two parts of it are machine-enforced by the spec-quality gate (intro prose and a ## Related footer):

A numbered H1: # NN. Title.
A metadata table directly under the H1 with three columns: Status (Normative / Informative / Draft), Depends on, and Related.
Intro prose — one content-first orientation paragraph between the metadata table and the first ## heading. Lead with what the chapter is about, not with a keyword.
Body sections (##), grouped by topic; rules presented as tables where the data is structured.
A ## Related footer — the annotated map of neighbouring chapters (see the rules below).

Normative vs informative

A normative chapter is required for conformance: an implementation conforms only if it satisfies the chapter’s normative text. An informative chapter (or note) clarifies and illustrates and imposes no requirement. Mark every chapter as one or the other, and mark an informative chapter explicitly with a > **Informative.** line near the top, the way this chapter does.

Conformance keywords belong only in normative text. Using MUST or SHOULD in an example, an intro, or an informative note is a classic mistake — it reads as a requirement where none is meant. Normative text does not have to use keywords: a plain declarative statement (“The element specifies a node type.”) is still normative. Reach for a keyword only where conformance genuinely hinges on the level.

Writing rules that hold up

A good rule is one a reader can act on and a grader can check:

One requirement per statement (atomic). If you can say “half of it is done,” split it. A sentence joined by “and” or “but” is usually two requirements.
Verifiable. Each rule must be checkable by inspection, analysis, test, or demonstration. Atomic plus verifiable means one rule maps to one clean pass or fail.
No weasel words. Avoid easy, fast, flexible, sufficient, adequate, user-friendly, robust, “as appropriate,” “where required.” Replace each with a measurable criterion.
Active voice, named subject. “The agent MUST validate the input,” not “it should be ensured that the input is validated.”
Descriptive first, then the clause. State what the thing is or does in plain language, then attach the conformance level.
Use the RFC keyword levels in ALL CAPS only. MUST / REQUIRED / SHALL are absolute. SHOULD / RECOMMENDED may be ignored only with a stated, understood reason. MAY / OPTIONAL is truly voluntary. Lowercase “must” and “should” carry no normative weight (RFC 8174). The conformance paragraph that defines this lives once in 00-overview.md; reference it rather than restating it.

Anchoring terms

Core terms shared across the organization are anchor terms: each has one canonical label, one owning chapter, and an explicit statement of what it is not. This container follows the org anchor-term convention (memo-init upstream, meta-spec 06-conventions-writing) rather than defining a second one. When a chapter here uses a shared term it uses the canonical label and respects the registered negative delimitation; a term specific to this container is qualified by the UP namespace token, so the same word in another family stays distinct. Grounding comes from consistent use across chapters, not from a glossary entry alone.

Cross-references: `Depends on` vs `Related`

Keep the two distinct:

Depends on is the set of upstream prerequisites a reader must read first.
Related is the set of lateral siblings, downstream chapters, and see-also links.

The top metadata Related field MUST NOT duplicate a Depends on entry. The bottom ## Related footer MAY list a dependency too, but only with a reason — at which point it is doing the annotated “see also” job, not repeating the prerequisite.

The `## Related` section — the rules

This is the part most often gotten wrong, so it is spelled out. Nine rules:

R1 — Two locations, two jobs (both mandatory). The top metadata Related field is a teaser: a short comma-separated inline list of the two-to-four closest siblings, links only. The bottom ## Related footer is the annotated map.
R2 — Every ## Related entry is link + reason. Format exactly: - [NN. Title](./NN-file.md) — one-line reason for the relationship. Never a bare link; the em-dash separates link from reason.
R3 — The reason describes the relationship, not the other chapter. Say how this chapter connects to the target, not a paraphrase of the target’s title.
R4 — Keep Depends on and Related distinct (see the section above).
R5 — The top field is a subset of the bottom list. Everything in the top Related cell appears in the bottom footer with its reason added; the footer may add a few more (the overview, the index). The two never contradict.
R6 — Every chapter opens with intro prose before the first ## (also machine-enforced).
R7 — Order entries for reading flow, not alphabetically: foundation first, then siblings in chapter order, then the index last if included.
R8 — No internal leaks in reasons. Outward specs carry no internal record ids, internal tool or CLI names, or absolute paths.
R9 — Reasons are short (roughly fifteen words or fewer), end with a period, and stay in one language.

Bad (bare links, no reasons, set disagrees with Depends on):

<!-- IMPLEMENTED-BY — rendered backlink lives in the dist (generated/bridge/<family>/<stem>.backlink.md); source stays authored-only (F2 Dist-Split) -->
## Related

- [00. Overview & Conformance](/specification/overview/)
- [01. Communication & Language](/specification/communication-and-language/)

Good (link + reason, ordered, relationship-specific):

## Related

- [00. Overview & Conformance](/specification/overview/) — the conformance language and glossary every rule here uses.
- [01. Communication & Language](/specification/communication-and-language/) — the tone and one-language rule this guide applies to spec prose.

Grading from the start

Every spec in this container carries a grading model from its first version. Each checkable rule is authored together with its grading point — a stable GR- code, a severity, and a check — so the spec is gradeable on day one rather than retrofitted later. Think of it as a funnel: broad, RFC-style normative text and its context narrow into deterministic grading points. The prose is the wide mouth of the funnel and the codes are its tip; a spec that states rules without grading points has built only half the funnel. If a chapter cannot name the grading point for a rule, that rule is guidance (a SHOULD without a code), not a conformance target — and stating so keeps the spec honest.

Versioning and structure

Put the spec under a versioned directory (v0.1.0/) and version it with SemVer per spec, so a downstream reader can pin a version and trust its rules do not shift under them.
Make 00-overview the entry chapter: it carries the scope, the conformance block, and the glossary.
Keep a README.md index with the reading order and a Normative/Informative column.
Use stable chapter numbers and anchors so cross-references survive edits; state prerequisites in Depends on.

Style

One language per artifact — these specs are written in English, with no mixed-language phrasing. Lead with the concrete; use a factual register with no hype. Tables carry structured data, prose carries reasoning. Never leak internal tool names, absolute paths, or internal identifiers into outward text.

Dual-use authoring: generate-context and review rubric

A chapter does double duty. The same page an agent reads before producing an artifact — the generate-context — is the rubric a grader or a human checks it against after. Writing the two as one document keeps generation and review from drifting apart: there is no separate prompt to maintain, because the rule the author reads is the rule the gate runs.

Two optional conventions make the double duty explicit:

A per-document self-review block — one [ ] checkbox per checkable rule, the way the checklist below models it — so an author confirms each rule before calling the page done.
A short authoring footer carrying the single most important governance reminder, the authoring date, and a revalidation cadence. The footer is an authoring-layer aid, not part of the published rule set; when a publish step strips authoring-only material, it strips this footer too.

A minimal footer reads:

<!-- AUTHORING FOOTER — authoring-layer only, stripped from the published payload. -->
> Last note for Claude: the single most important reminder for this document.
> Authored: <yyyy-mm-dd> · Revalidate: quarterly.

Keep the footer out of the normative body: it is a note to the author, never a conformance target.

Checklist before done

A new chapter is ready when:

It has a numbered H1 and a metadata table (Status / Depends on / Related).
It opens with intro prose before the first ##.
It is marked Normative or Informative; conformance keywords appear only in normative text, in ALL CAPS.
Each rule is atomic and verifiable, with no weasel words.
Shared terms use the canonical anchor-term label and respect its registered negative delimitation.
Each checkable rule names its grading point (GR- code), severity, and check.
## Related is present; every entry is link — reason; the top field is the teaser subset and duplicates no dependency.
No internal leaks; one language throughout; the README index is updated.

00. Overview & Conformance — the scope, conformance keywords, and glossary this guide tells you to reuse.
01. Communication & Language — the one-language, lead-with-the-concrete style applied to spec prose.