writing-documentslisted

# Writing Documents A technical document exists to get a reader to a decision, or to a working understanding, without them having to reconstruct the author's thinking. The failure mode is not ugliness. It is a document that is complete, accurate, and unreadable — where the reader cannot find the decision, cannot tell what is settled versus proposed, and cannot see what changed since they last read it. This skill is two layers. Do not glue them together. 1. **Writing** (default) — pick the type, load its shape, write from evidence. Output is Markdown in the user's tree. 2. **Design system** (opt-in) — tokens, themes, print, self-contained HTML. Load `core/` only when the user asked for HTML, PDF, print, a designed page, or "use the design system". ## Format first `format = markdown`, unless the user asked for `html`, `pdf`, `print`, `designed`, `themed`, or "use the design system". | Format | Load | Do not load | |---|---|---| | `markdown` | this file, the type file, `references/writing.md`, `references/evidence.md` | `core/`, themes, `templates/longform.html`, print.css, `build_document.py` | | `html` / `pdf` | the above plus `references/output.md` and `core/` | — | | `both` | Markdown first (canonical in-repo), then HTML from that source | — | Full dial, conventional paths, and HTML assembly: `references/output.md`. On the Markdown path, leave Mermaid as fenced blocks. Prerender to themed SVG only on the HTML path. State the assumption in one line. Do not quiz. >