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 shape (a type, or a composition from a pattern), 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".

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.

Writing docs/adr/adr-014.md as type adr (markdown). Designed HTML on request.

Ask only when the slug is actually ambiguous or the request conflicts with another skill. If they asked for HTML and named no theme, use the type file's default-theme. Do not quiz. field-notes is only a fallback when the type has not been resolved yet.

Never offer a designed HTML version unprompted.

Pick the shape

Type first; compose when none fits.

1. A type fits. Load references/type-index.md if the slug is unclear, then load that references/type-<slug>.md before writing. The canonical catalog has 34 types grouped by reader movement; common labels such as HLD, LLD, TDD, PRD, API spec, PRR, and RAID route there as aliases rather than duplicate files or commands.
2. No type fits. Do not force the nearest preset. Pick the pattern from the reader's-question table in references/type-index.md, then follow references/composing.md: modules allowed for that pattern, the nearest type's section discipline, and front matter type: custom with pattern, modules, and nearest-type. A composed shape seen three times becomes a type.

If several reader questions apply, split. Two clear documents beat one that mixes a decision with a 3am checklist. Use references/consultancy-lifecycle.md for an engagement-spanning request and references/suites.md for linked sets.

The compatibility command mulesoft loads type-service-docs.md plus references/profile-mulesoft.md; it is not a second canonical type.

Evidence before prose

Mark claims the reader might not be able to check:

Full rules, privacy, and the optional business-context checkpoint: references/evidence.md.

Writing

The design system cannot rescue unclear writing, and clear writing survives bad formatting. Depth in references/writing.md.

• Lead each section with its conclusion.
• One idea per paragraph.
• Prefer prose to bullets for reasoning. Bullets are for enumerable things.
• Define terms on first use; use the same term throughout.
• Put numbers in the sentence when numbers exist.
• Name the actors. "It was decided" hides who can revisit it.
• Non-goals, real alternatives, and open questions with owners — omit only on purpose.
• Status explicit: Draft, Proposed, Accepted, Superseded by <link>, Deprecated.
• Headings are claims or questions, not labels. Stable IDs derived from the text, never auto-numbered.
• Cross-references by name, not section number.

HTML path only

When format is html or pdf, references/output.md applies in full. Short version:

• Assemble from templates/longform.html. The type reference — or a composed document's front matter — declares the root data-pattern; theme stays independently selectable on data-theme.
• Keep prose at 62–72 characters. Let maps, tables, timelines, comparisons, and registers use the wider shell when the pattern calls for them.
• Diagrams from diagram-design; charts from chart-design.
• Print via core/print.css. Inspect the PDF; do not claim print support from @media print alone.
• No JavaScript required to read the file.

Pattern before theme

Pattern answers how the reader moves; theme answers what visual voice they hear. Do not use theme changes to simulate structural distinction.

Use the type reference's default pattern and theme; a composed document uses its declared pattern and the nearest type's theme. The full layout, module registry, and acceptance contract is core/document-patterns.md. The invocation below uses field-notes as a concrete example; pass the type's default-theme instead.

python3 "<skill-dir>/scripts/build_document.py" \
  "<skill-dir>/templates/longform.html" \
  --theme field-notes --out document.html
node "<skill-dir>/scripts/export_pdf.mjs" document.html --out document.pdf

core/…, scripts/… and templates/… are relative to this skill's directory — the folder that contains this SKILL.md — not to your working directory. The skill carries its own copy, so it works however it was installed.

Leave alone

• Casual edits to existing Markdown (typos, one extra paragraph, a changelog bullet).
• Metric-led reports → analytical-document-design.
• Slides → presentation-design.
• Standalone charts or diagrams.
• Restyling Markdown into HTML, or applying a theme, unless asked.
• MSAs, NDAs, invoices, procurement, HR, or invented legal clauses. A statement of work uses only delivery-commercial terms the user supplied.
• Generating Mule XML or running MUnit. Mule markdown refresh when mule-docs is installed — prefer that skill.
• Rewriting a README that already has a shape the user did not ask to change.

Before delivering

• Format matches the request (markdown unless they asked for designed output).
• The type's or composition's expected sections are present, or their absence is deliberate.
• A composed document declares type: custom, its pattern, nearest type, and only modules that pattern allows.
• Inferred claims are labelled; unresolved items are open questions.
• Every section leads with its conclusion.
• Terms are defined on first use and used consistently.
• Heading IDs are stable and text-derived; cross-references are by name.
• HTML path only: measure 62–72ch, prints without stranded headings or clipped code.

Reference files

• references/type-index.md — reader's question → pattern, slug, aliases, path, shipped types.
• references/composing.md — compose from a pattern when no type fits; promotion rule.
• references/type-design-doc.md
• references/type-adr.md
• references/type-spec.md
• references/type-api-contract.md
• references/type-architecture.md
• references/type-handoff.md
• references/type-design-handoff.md
• references/type-discovery.md
• references/type-test-report.md
• references/type-postmortem.md
• references/type-proposal.md
• references/type-runbook.md
• references/type-onboarding.md
• references/type-tutorial.md
• references/type-how-to.md
• references/type-reference.md
• references/type-explanation.md
• references/type-project-charter.md
• references/type-estimate.md
• references/type-change-request.md
• references/type-requirements.md
• references/type-statement-of-work.md
• references/type-support-model.md
• references/type-delivery-plan.md
• references/type-migration-plan.md
• references/type-test-strategy.md
• references/type-threat-model.md
• references/type-readiness-review.md
• references/type-risk-register.md
• references/type-status-report.md
• references/type-release-notes.md
• references/type-workshop-summary.md
• references/type-incident-update.md
• references/type-service-docs.md
• references/profile-mulesoft.md — compatibility profile for the generic service suite.
• references/consultancy-lifecycle.md — minimum linked sets by engagement stage.
• references/writing.md — prose, headings, review mechanics.
• references/evidence.md — evidence states, privacy.
• references/suites.md — when to emit a linked set.
• references/output.md — format dial, HTML/PDF assembly.