language-spec-author

# Author an Implementable Language Specification Take an author from a rough language idea to a specification precise enough that a developer with **zero access to the author** can build a conforming implementation from the document alone. The output is a spec in the mold of the [GraphQL specification](https://spec.graphql.org/draft/) — grammar, semantics, validation, execution, and conformance — that other devs can implement and interoperate against. The hard part of a language spec is not prose; it is eliminating the ambiguities the author does not know they are leaving. Two implementers reading a vague sentence produce two incompatible languages. So this skill's method is **grilling**: ask one sharp question at a time, recommend a default, and refuse to write down any answer that fails the stranger / edge-case / two-implementers tests. It bundles a scaffold script, a completeness linter, and reference docs for the anatomy, the formal notation, and the interview itself. ## When to Apply - The user wants to **design or formalize a language**: a DSL, query language, config or data format, template language, expression language, or wire protocol. - The user has a **working idea or prototype** and needs a written spec others can implement against — "spec out my query language", "formalize this syntax". - The user asks for a **grammar, a language spec, or an implementable definition** and needs the lexical/syntactic/semantic structure worked out, not just examples. - The user has a spec draft that **implementers keep asking questions about** — the holes need to be found and closed. Do **not** use this for: authoring a Python language proposal (use `python-pep-author`), an internal company RFC or design doc (use `dev-rfc` / `feature-spec`), or documenting an API surface that already has a fixed definition. ## Prerequisites - **Bash + coreutils** (`awk`, `sed`, `grep`, `date`) for the two scripts — present by default on macOS/Linux. No language runtime is required to draft or lint. - The author available to answer questions. This skill is an interview; it cannot invent the language's decisions, only extract, pressure-test, and record them. ## Workflow Overview The interview walks the pipeline every implementable spec must describe — source text → tokens → tree → validated tree → result — grilling at each stage. Phase 0 decides which parts apply; not every language needs all of them. ``` 0. Frame ──► 1. Purpose & ──► 2. Lexical ──► 3. Syntactic the principles grammar grammar language (tie-breakers) (chars→tokens) (tokens→AST) │ ▼ 8. Conformance ◄─ 7. Output & ◄─ 6. Execution ◄─ 5. Validation ◄─ 4. Semantic model (MUST/SHOULD/ error format (algorithms + (static rules + / type system MAY, normative) (result+errors) error model) counter-examples) (optional) │ ▼ Scaffold (new-spec.sh) filled section by section ──► Lint (check-spec.sh) ──► Cold-read test ``` Scaffold once, early, so answers land in a structured document as they are settled: ```bash scripts/new-spec.sh --title "AcmeQL" --goal-symbol "Document" --editors "R. User <r@x.io>" ``` ### 0. Frame the language Before any grammar, establish what kind of language this is — query, config, imperative, declarative, protocol, template — because that decides which anatomy parts apply. A pure config format may have no execution section; a query language needs all eight. Ask the Phase-0 questions in [references/interview-playbook.md](references/interview-playbook.md) and read [references/spec-anatomy.md](references/spec-anatomy.md) to see the eight parts and mark which are in scope. Absent parts must be a **stated choice**, never a silent gap. ### 1. Purpose & design principles Pin the purpose, the non-goals, and 3–5 design principles. Principles are the tie-breakers that resolve every ambiguity the spec did not foresee, so grill each one: "what future decision does this principle pre-resolve?" ### 2–3. Lexical then syntactic grammar Define tokens (`::`, characters → tokens) before structure (`:`, tokens → AST). Read [references/formal-notation.md](references/formal-notation.md) first — the two-colon discipline and the shorthands (`?`, `+`, `but not`, lookahead) are what keep the grammar unambiguous. This is where authors under-specify most: whitespace significance, case sensitivity, comment syntax, exact literal patterns, and — the classic hole — **operator precedence and associativity**. Actively hunt ambiguity; an ambiguous grammar is not implementable. ### 4. Semantic model / type system (if applicable) If the language talks about typed entities, schemas, or resources, define that model separately from the grammar, with its constraints and (optionally) introspection. ### 5. Validation (static semantics) Enumerate every way a document can parse yet still be invalid. Write each as a **named rule** with a formal specification, explanatory text, and a **counter-example** (the smallest invalid document). The counter-example doubles as a test case and proves the rule is decidable. ### 6. Execution (dynamic semantics) Specify evaluation as **named, function-style algorithms** (formal-notation.md), not prose. Force the three decisions authors skip: **evaluation order** (only where observable), **coercion** rules, and above all the **error model** — does an error abort, propagate to a boundary, or yield a partial result? Every algorithm path must return or raise a defined error. ### 7. Output & error format The observable result shape, the error object shape (message, location, path, extensions), and at least one concrete serialization. Under-specifying the error format is a top interop failure — clients written against one implementation break on another. ### 8. Conformance Adopt RFC 2119 keywords, declare the normative/non-normative split, and include the observably-equivalent clause so implementations can optimize. The template's conformance section is pre-filled to the GraphQL convention. ### Finish: lint, then cold-read Run the linter to catch structural holes, fix every FAIL, then apply the real test: ```bash scripts/check-spec.sh acmeql-spec.md ``` `check-spec.sh` finds mechanical gaps (missing sections, unresolved `TODO`s, missing grammar notation, absent conformance keywords). It **cannot** judge whether the semantics are correct — that is the **cold-read test**: hand the draft to a developer with no context. Every question they must ask you is a defect; fold the answer back in. ## Reference Files | File | Read it when | |------|--------------| | [references/spec-anatomy.md](references/spec-anatomy.md) | Framing scope (Phase 0) and checking completeness — the eight parts of an implementable spec, what each answers, and the done-bar for each | | [references/formal-notation.md](references/formal-notation.md) | Writing the grammar (Phases 2–3) and semantics (Phases 5–6) — lexical vs syntactic notation, algorithm notation, data collections, RFC 2119 keywords | | [references/interview-playbook.md](references/interview-playbook.md) | Running the interview — the grilling stance, the three rejection tests, underspecification detectors, and the per-phase question bank | ## Scripts | Script | What it does | |--------|--------------| | `scripts/new-spec.sh` | Scaffolds a spec draft from the template, filling title/date/version/goal-symbol. Run with `-h` for usage. | | `scripts/check-spec.sh` | Lints a draft for structural holes (missing sections, unresolved placeholders, grammar notation, conformance keywords, counter-examples) → PASS/WARN/FAIL, non-zero exit on any FAIL. | The template the scaffold fills lives at [assets/templates/spec-template.md](assets/templates/spec-template.md) — copy it directly if you would rather fill the sections by hand. ## Gotchas See [gotchas.md](gotchas.md). The recurring ones: authors describe the happy path and skip the **error model**; lexical (`::`) and syntactic (`:`) grammar get conflated; evaluation order is specified everywhere or nowhere (specify it only where observable); and a spec that *reads* complete still fails the cold-read test. ## Related Skills - `radical-simplification` — its `clarify-interview-one-at-a-time` move is the interview discipline this skill applies to language design. - `python-pep-author` — proposing a feature to upstream Python (a governance process, not a from-scratch language spec). - `dev-rfc` / `feature-spec` — internal RFCs, design docs, and feature specs (not formal language definitions).