#Documentation Conventions

This document defines the standards for all documentation in docs/. Following these conventions ensures consistency and discoverability.

---

#Required Front-Matter

Every markdown file in docs/ must include YAML front-matter with these keys:

---
title: Document Title
status: draft
version: "1.0"
last_updated: 2025-12-13
scope: architecture
---

#Keys

Key	Required	Values	Description
title	Yes	Free text	Human-readable document title
status	Yes	draft, stable, deprecated	Current lifecycle state
last_updated	Yes	YYYY-MM-DD	Date of last substantive change
scope	Yes	See below	Document category

#Status Values (Unified Taxonomy)

Allowed values: draft | active | stable | locked | deprecated | archived

Status	Meaning	Modifiable?	Rules
draft	Incomplete, evolving, or mid-refactor	Yes	Not safe for automation or authoritative reference
active	Actively maintained, in use	Yes	Current working documents undergoing regular updates
stable	Reviewed, trusted, production-ready	Minor updates only	Expected to change slowly and intentionally
locked	Completed or superseded, preserved for history	No	Plans and versioned artifacts that must not change
deprecated	Historical only, retained for context	No	Must include replaced_by link (see below)
archived	No longer relevant, read-only reference	No	Kept for audit trail; may be purged periodically

Usage by document type:

• General docs typically use: draft → stable → deprecated
• Plans (in docs/plans/, .claude/plans/) typically use: draft → active → locked → archived
• See Plan Governance Rules for plan-specific lifecycle rules.

Enforcement rules:

• New documents default to draft
• deprecated requires either:
  • A replaced_by: field in front-matter, OR
  • A "Replacement:" line at the top of the document body
• Documents marked stable that appear speculative or incomplete must be downgraded to draft
• deprecated documents without replacement links are invalid
• locked documents are protected by pre-commit hooks — create a new version instead of modifying

#Promotion Policy

Promoting documentation from draft to stable is a verification event, not a formatting step.

1. New documents default to draft — All new documentation starts as draft
2. Verify against code before promotion — Documentation must match implemented behavior
3. Correct mismatches first — If docs and code disagree, fix the discrepancy; reality wins
4. Schema docs require schema match — Database/API docs must reflect actual schema
5. Promote in a dedicated commit — Promotion changes are isolated, not mixed with code changes
6. Update last_updated — Change the date when promoting status
7. Treat stable as contract — Stable docs are authoritative; changes require review

#Scope Values

• reference — General reference docs (glossary, conventions, README)
• architecture — System design, ADRs, technical specs
• dev — Developer guides and setup
• operations — Runbooks and operational procedures
• product — PRD, user guides, product definitions

---

#File Naming Rules

All documentation files use kebab-case:

• Lowercase letters only
• Words separated by hyphens
• No underscores, spaces, or camelCase
• Extension: .md

#Examples

Correct	Incorrect
local-development.md	localDevelopment.md
incident-playbook.md	incident_playbook.md
monorepo-structure.md	Monorepo Structure.md

#Exceptions

• README.md — Always uppercase (convention)
• CONVENTIONS.md — Uppercase for repo-level standards
• CONTRIBUTING.md, SECURITY.md, CHANGELOG.md — Repo root files follow GitHub conventions

---

#Cross-Linking

Use relative paths for all internal links. Never use absolute URLs or file:// paths.

#Within the Same Directory

See [Incident Playbook](./incident-playbook.md)

#To Parent or Sibling Directories

See [Architecture Overview](../architecture/overview.md)

#To Repository Root Files

See [CONTRIBUTING.md](/CONTRIBUTING.md)

#Rules

1. Always include the .md extension
2. Use ./ prefix for same-directory links
3. Use ../ to traverse up directories
4. Use / prefix for repo root files only
5. Link text should be the document title or a clear descriptor

#Directory Index Links

When linking to a section's index, link to the directory with trailing slash or to README.md:

See [Development](./dev/) for setup guides.

---

#When to Create a New Document

Create a new file when:

• The topic is independently discoverable (someone might search for it)
• The content exceeds ~200 lines
• The topic has a distinct audience or lifecycle
• It's a runbook for a specific system component
• It's an ADR (append to decisions.md instead—see below)

Extend an existing file when:

• Adding a section to an established topic
• The content is tightly coupled to existing material
• The addition is a natural elaboration, not a new subject

#Special Cases

Content Type	Action
New ADR	Append to architecture/decisions.md
New glossary term	Add to glossary.md
New runbook	Create separate file in runbooks/
New product definition	Create separate file in product/

---

#Directory Structure

Each directory must have:

1. README.md — Index listing all documents in that section
2. Individual topic files in kebab-case

When adding a new file, update the parent README.md to include it.

---

#Document Structure

#Title

• Use a single # Title matching the front-matter title
• Do not repeat the title as a second heading

#Sections

• Use ## for major sections
• Use ### for subsections
• Avoid going deeper than ####

#Horizontal Rules

Use --- to separate major logical sections (as seen in runbooks and ADRs).

---

#Updating Documents

When making substantive changes:

1. Update last_updated in front-matter
2. Preserve the document's original structure where possible
3. If deprecating, change status to deprecated and add a note pointing to the replacement

---

#Exemptions

Some directory patterns use alternative conventions:

Pattern	Convention	Reason
docs/prompts/*/	Uses 00-index.md as index	Prompt directories use numbered prefixes for ordering
docs/projects/*/	Uses TODO.md as primary file	Project directories are GTD-managed with TODO trackers
docs/done/YYYY-mon/	No index needed	Chronological archive — browsed by date, not by index
docs/templates/doc-creation/	Template files with {{placeholders}}	Templates intentionally use invalid frontmatter values

---

#Summary

Rule	Standard
Front-matter	title, status, last_updated, scope
Status values	draft, active, stable, locked, deprecated, archived
File names	kebab-case with .md extension
Links	Relative paths with explicit extension
New vs extend	Independent topics get new files; related content extends existing
Directory index	Every folder has README.md (see Exemptions for exceptions)