---
name: the-system-markdown
description: "Use when writing Markdown for a System document: research, spec, phase, plan, or issue bundles under .system/."
---

# The System Markdown contract

Use readable Markdown.
Model structure, sequence, state, entities, and decisions visually by default.
Use prose for intent, judgment, and constraints.
When content is a structure, flow, state machine, relation, comparison, or branch, select a format first, then load its matching `the-system-*` skill.
Mermaid models systems, GFM tables enumerate comparisons, TeX states formal relations, raw HTML mockups show visual or interactive surfaces.
Terse governs prose, not models; a diagram that replaces a paragraph is the terse form.
Keep local Markdown links relative so `/system view` and `/system book` can resolve them; use absolute HTTPS links for external sources.
Task lists contain only static checkable criteria and remain unchecked; operational state belongs in `.system/board.json`.
Never diagram `/system` stage progression or plan, spec, issue, or board progress.
Replace or remove obsolete canonical text instead of retaining it with strikethrough.
System documents contain no real code snippets; use terse pseudocode only when essential.