Skip to content

Design documents

What's inside

Path Purpose
skills/writing-design-documents/SKILL.md When to use the skill, the workflow, how the text should read, and common mistakes
skills/writing-design-documents/scripts/docbuilder.py DesignDoc builder (cover text, change record, headings, tables in the template's colours, landscape figure pages), finalize (Word: TOC, fields, PDF) and check
skills/writing-design-documents/examples/example_design_doc.py Worked example (fictional Contoso): current state, findings, figure page, implementation plan
tests/selftest.py Checks the typesetting, that a clean build passes, and that every check rule fires
docs/sample.pdf Output of the example on a plain template
cli.mjs, install.mjs npm package: init, uninstall and doctor

Check reports what makes a document look machine-made or reveals how it was produced: em and en dashes, "·" and "+" separators, straight quotes, bold lead-ins, arrows or semicolons in running text, repeated paragraphs, references to sections that don't exist, wording about how facts were collected ("read-only", "CLI", "logs show"), common AI vocabulary, empty pages, table titles separated from their table, and captions separated from their figure.