Documentation Model

This repository deliberately separates current truth, planned work, future intent, and historical decisions.

Document classes

Living normative docs

Locations:

• product/
• design-system/

These describe the product and design system as they are currently intended to operate. Update them when the system changes.

Living technical docs

Location:

• platform/

These describe the approved technical model.

At repository creation, platform documents may be proposed. Once implementation exists and a document accurately describes reality, change it to active.

Do not leave obsolete aspirational architecture in place after implementation diverges.

Planning docs

Locations:

• planning/active/
• planning/completed/

PRDs describe scoped work, not current capability.

Typical lifecycle:

draft → ready → active → completed

Alternative terminal states:

• superseded
• abandoned

When a PRD completes, move it to completed/ and update living documentation to describe the resulting system.

ADRs

Location:

• decisions/

ADRs explain why important decisions were made.

Accepted ADRs are historical records. Supersede them rather than rewriting history.

Roadmap

Location:

• roadmap/

The roadmap describes future intent and sequencing. It is never proof that a feature exists.

Authority metadata

Durable documents carry lightweight frontmatter:

---
title: Document title
type: design-standard
status: active
authority: normative
lifecycle: living
---

Authority values:

• normative — current product/design-system rule.
• technical — technical direction/current architecture.
• planning — intended scoped work.
• historical-decision — rationale from a point in time.
• future-intent — roadmap or future direction.

Lifecycle values:

• living — update as reality changes.
• time-bounded — close/archive when work ends.
• immutable-history — preserve history; supersede instead of rewriting.

What is current reality?

For implementation behavior, prefer:

1. source,
2. tests,
3. released component contracts,
4. current technical docs.

For design-system rules, use living design-system docs and contracts.

For product intent, use living product docs.

PRDs, ADRs, and roadmaps serve different purposes and should not be promoted above those sources.

Documentation maintenance

A change is not done if it materially invalidates a living document and leaves that document stale.

Every meaningful pull request should ask:

Does this change alter public behavior, component contracts, architecture, agent guidance, or a living design-system rule?

If yes, update the relevant durable documentation in the same change.