Documentation Standards

Documentation Standards

This is a meta-skill: a rule that applies across every stage rather than belonging to one. Whenever any stage skill in this plugin produces or reviews a Markdown document — a design doc, a plan, an ADR, a README, a competency file — the formatting, metadata, diagram, linking, and table rules below govern it, read live from this plugin's own skills/documentation-standards/documentation-standard.md every time this skill runs. There is no separate paraphrased copy anywhere, so this content cannot silently drift the way a hand-maintained summary could.

Documentation standard (live)

!cat "${CLAUDE_PLUGIN_ROOT}/skills/documentation-standards/documentation-standard.md"

Instructions

1. Apply the Required Metadata front-matter shape to every active Markdown document you write or edit — id, title, type, status, owner, priority, tags, depends_on, related, last_updated — using only an Approved Document Type and an Approved Lifecycle Status from the lists above. Machine-readable YAML manifests are the one named exception; they do not use this envelope.
2. Before adding a Mermaid sequenceDiagram, check the Mermaid Sequence Diagram Rules' required-cases list (cross-capability workflows, broker/event flows, orchestration/state transitions, auth/token flows, external-provider integrations, multi-service async user actions) — if the design matches one of these and has no sequence diagram, treat the design as incomplete unless you record why prose is clearer, per the Acceptance rule stated above.
3. Before adding a Mermaid stateDiagram-v2 to an erd.md, check whether the entity's field is genuinely status-shaped (a closed, named set of values with documented transition rules) per the State Diagram Rules above — a plain enum with no enforced sequencing does not require the diagram; a status field with real transition rules and no diagram makes the ERD incomplete.
4. Use the Link And Cross-Reference Rules above exactly: Markdown links for prose references, reference-style links for repeated references, anchors for stable sections, source aliases (@backend, @frontend, @product-knowledge) only in command examples/entrypoint lists/alias documentation — never as a substitute for a real Markdown link to another document. Note the one deliberate exception recorded above for citing an ephemeral or non-canonical planning artifact (a retired per-milestone tracking document, or the current session's own ExecPlan under .agent/exec-plans/): write that citation as backticked prose naming what it is, never as a Markdown link.
5. Use the Table Writing Rules above to decide whether a table or prose is the right shape — required for ownership matrices, canonical-source maps, status/readiness matrices, API/integration catalogs, permission catalogs, glossaries, migration maps, and validation-evidence summaries; avoid tables for narrative reasoning, decision rationale, or long prose.
6. For canonical-ownership questions this document doesn't resolve on its own (the Owns/Must-Not-Own table and knowledge-layer/reference-direction rules), defer to the governance meta-skill's injected documentation-governance.md content rather than guessing or restating it here — this document explicitly does not own that table.
7. If you are re-reading this skill after skills/documentation-standards/documentation-standard.md changed, trust what you just read above over any memory of a previous run — that live content is always the current source of truth for documentation formatting in this knowledge base.