Canonical Docs

This skill is guidance, not a script. Give useful explanations a clear owner. Code is the source of truth for actual behavior; requirements and valid decisions define intended behavior. Tests are evidence, not infallible authority. A discrepancy may be stale prose or a defect: determine which before changing the explanation.

When not to use

• The sentence-level contract of a passage. Use prose-standard.
• Prose that takes the authoring session's vantage. Use trim-reasoning-leakage.
• The rationale for a design decision. Use decision-records.

Inputs and authorization

• Required: the reader and the judgment or operation the text helps them perform.
• Authorization: a scoped edit does not authorize restructuring the whole corpus. Establish a new documentation structure only after the user chooses among options.

Method

Keep local mechanics beside code, module contracts with their module, and cross-module relationships at the system level. Higher pages explain purpose and guide readers to detail. Decision records own why a design was chosen; ordinary documentation owns the current explanation, not the decision history.