SKILL.md
Writing design docs
REQUIRED BACKGROUND: the technical-writing skill (read-first, hard rules, truth rules, style).
Overview
A design document is a proposal made discussable: conclusion first, every non-trivial choice in a Why & What box, costs named next to benefits, and fact separated from proposal.
When to invoke, and not
Invoke for anything that argues for a change or records a design: proposals, RFCs, design docs, specs, migration plans, "should we" documents. Do NOT invoke for recording an already-taken decision (recording-decisions), for procedures (writing-runbooks), or for status reports.
Under pressure: a proposal persuades with its numbers and its named costs, and the register rules hold whatever the deadline (the technical-writing rule; "punchy" is not an override). When supplied facts arrive without sources, mark them **[source wanted: ...]** and keep writing (see references/truth.md in the technical-writing skill); never invent a citation and never silently drop the fact.
Skeleton
# Title: what the document does