writing-docs

name	writing-docs
description	PRD editorial standard for docs/. Use when writing a new PRD, extending one, or reviewing changes under docs/ — and when another skill needs the PRD rules.
allowed-tools	Read, Edit, Write, Grep, Bash

writing-docs

A PRD records a layer's invariants — what stays true across every implementation of that layer. This skill is the standard that keeps a PRD worth reading: durable, load-bearing, one fact in one place. A PRD is not an API reference, not a code map, not a changelog, not a task tracker.

The agent's default is to write down whatever seems useful right now. But a stale or duplicated line is not free storage — it is a distractor that pulls the model off the invariant that matters. Two gates and one home rule replace that default.

Pick your branch:

• New PRD → the Anatomy template, every line through The two gates.
• Extending a PRD → run The two gates on what you add; before inserting, check Single home (the fact doesn't already live elsewhere).
• Reviewing docs/ changes → Reviewing a diff.

The two gates

A line earns its place only if it passes both gates. If it fails, delete it — don't reword it.

1. Durable, not status. The line is true independently of the current code. A sentence a merged PR could falsify is status, and status has another home. Fails the gate: line numbers (lib.rs:108), "current state / first vertical slice / WIP / TODO / stub / filled in by later slices / awaiting /audit", percent-done, "not yet implemented", inventories of what already emits vs. what will. Write the target invariant — true in six months ("the template is emitted here, the script in the transform") — not a snapshot of progress ("only static attributes are emitted so far"). Partial coverage of a feature goes in an issue link, never an inline slice list.

2. Load-bearing. The line changes a decision when writing or reviewing code. Test it: delete the line — does any implementation choice change? No → it's a no-op (a default the agent already honors: "code must be correct", "follow the principles") — cut it. A weak invariant is sharpened into a checkable one, not kept for volume. A checkable invariant carries its mechanical check where one exists: "grep Emit over the crate is empty", "enforced by the Node enum macro". Where none exists, anchor it with one canonical example, not an enumeration of every form — an example is a compressed check read at a glance; the exhaustive list is the wall of text that rots first.

Single home

Every fact lives in exactly one document. A copy in two places bloats context and desyncs first.

Fact	Home
Glossary term / ubiquitous-language definition	context.md
Where code lives (crate, module, entry point)	map.md (crate/module — no :line, it drifts)
A layer's invariant	that layer's PRD, and only there
Status / progress / TODO / work plan	GitHub Issues
Why a decision was made (rationale)	docs/adr/ or docs/designs/ — the PRD carries the rule, the ADR the reason

A PRD names a glossary term (bold on first use) but never redefines it. Moving a fact to another home means deleting it from the old one — one copy in two places is a defect, not a backup.

The topics contract

The lines right under a PRD's title:

label: <slug>
topics: <canonical glossary terms, comma-separated>

topics: exists for one consumer: the required skill greps this line to pull the PRD into context by a task's terms, never judging by filename. How it greps is required's to own; how you write the line follows from it:

• List every canonical term the PRD owns. A term you omit makes the PRD unreachable for it — a routing gap. Over-listing is free (an extra grep hit costs one glance); a missing term is the failure, so bias toward more.
• Canonical glossary term, not an _Avoid_ synonym. The searcher names terms in glossary vocabulary (required maps synonyms through _Avoid_), so a topic must match that vocabulary. Term not in the glossary yet → add the article to context.md first, then list it here.
• Bare, greppable stem. required greps the stem (derived, each, bind), not the decorated form. Make the stem a literal substring: derived already covers $derived / OptimizedDerived; write each (or EachBlock), never only {#each}.

Add a concept to a PRD → add its term here in the same edit. A PRD without topics: is invisible to routing.

Anatomy

Title and frame, then the sections the layer needs — take what applies, not all of them.

# PRD: (root)

label: topics:

<1–2 sentences of frame: the crate(s), the place in the pipeline, the layer's principle, the client/server counterpart.>

Purpose

The single question this layer answers. One paragraph.

<substance — one or two of these>

What lives here · ## Public API · ## Traversal skeleton · ## Inputs / outputs

Architectural invariants

Numbered. Each opens with a bold lead and passes The two gates. Mechanical check inline where one exists.

Anti-patterns

Concrete violations to scan for (*Emit* reads, template knowledge in the transform) — the recognizable bad forms, not a re-wording of the invariants above.

Cross-document links

Cross-links with section anchors (context.md §"Principles").

Prose: compiler terminology over anything else; a glossary term bold on first use; no connective filler; the CLAUDE.md identifier ban holds in examples too.

Reviewing a diff

Run The two gates on every added line, and check Single home and The topics contract — most review findings are just these three by name. Two the gates don't cover: the Anatomy prose conventions hold (glossary term bold, from the glossary not an _Avoid_ synonym, no banned identifier); anchors in Cross-document links resolve to sections that exist.