writing-design-docs

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: writing-design-docs
description: Use when writing a proposal, RFC, design document, spec, or migration plan - anything that argues for a change, records a design, or asks readers for input on one. Encodes the proposal skeleton, the Why & What decision box, and the completeness checks. Use whenever a change needs arguing or scoping in writing, even if the user just says "write up the approach".
---

# 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

```markdown
# Title: what the document does

**Subtitle pinning the scope in one sentence**

|                |                                            |
| -------------- | ------------------------------------------ |
| **Status**     | Draft / Request for comments               |
| **Owner**      | [team or role]                             |
| **Scope**      | [explicit, including what falls outside]   |
| **Related**    | [links to sibling documents]               |
| **Audience**   | [who must read this]                       |

---

## 1. Summary
[The conclusion immediately. Not the occasion, not the method.]

## 2. [Context / what was analyzed]
## 3. [The analysis, split per question]
## n. Open questions
## n+1. Benefits and costs
[Both. Benefits alone reads as a sales pitch.]
## n+2. Residual risks and what not to do
[Only when the design hands work to other teams.]

---

*Closing line: which parts are fact and which are proposal, and where input is wanted.*
```

## Structure rules

- **Number chapters** and cite them as `ch. 7.1`.
- **Goals and non-goals both.** The non-goals (or "explicitly not changed") section states what stays unchanged.
- **Definitions before behavior** when a term is ambiguous: pin "responded", "eligible", "stale" before using them.
- **A grounding section** pins the facts the design rests on: a fact/source table, checked against a named commit. Separate verified facts from what will be built.
- **Appendices** take letters (Appendix A, B) and hold what would bury the main text: config examples, glossaries, inventories.
- **A fact lives in one place.** Link to it; never repeat it, not even across documents in the same repo.
- **Mark unfinished parts** with `**[DRAFT - input wanted]**` instead of omitting them.
- **Open questions get owners**: a name, a role, or an explicit "to be filled by".
- **Residual risks and what NOT to do** close the document when the design ships work to others.
- **No line budget**, but length from repetition or emphasis goes; past roughly 800 lines, split and let the main document link to the parts.

## The Why & What box

Every non-trivial choice gets one; readers react to the box, not to the conclusion.

```markdown
> **Why & What - [the choice in four words]**
>
> **What:** [the choice, one sentence, no justification]
>
> **Why:** [the reasoning. Also name what the choice does NOT solve.]
>
> **Alternatives considered:**
> - *[Alternative]:* [its strongest argument, and why it still lost]
>
> **Fallback:** [what survives if this does