docs-conventions

To enforce required frontmatter in markdown documentation, you validate metadata fields like title, status, audience, owner, and dates before considering a file complete. This prevents documentation drift by ensuring a consistent frontmatter schema across all markdown files.

Documentation taxonomy is a classification system that maps each markdown file to the correct docs subfolder based on its archetype, such as spikes, decisions, overviews, or roadmaps. You need it to keep documents organized, discoverable, and shippable across large projects.

To add lineage to markdown docs, include related, supersedes, prd, pr, and commit links in the document metadata. This ensures documentation can be traced across decisions and updates, preserving retrieval quality and documentation integrity over time.

To place an ADR or runbook correctly, map the document to its proper docs subfolder based on its archetype. Applying folder and archetype enforcement ensures spikes, decisions, overviews, and roadmaps stay organized and follow the correct scaffold.

Existing markdown files require frontmatter metadata to be considered complete. Without validated metadata fields and correct folder placement, the documents will not maintain the taxonomy standards needed to preserve retrieval quality and documentation integrity.

The limitation of enforcing a single documentation taxonomy is that all markdown files must strictly conform to the predefined folder placement and frontmatter schema. Documents that do not fit the supported archetypes or lack required lineage fields will fail validation.