> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/prd-shared/doc-standards.md).

# Documentation Standards

> **Last Updated**: 2026-02-17 | **Referenced by**: All PRDs
>
> This is the **single source of truth** for PRD writing conventions, spec semantics, and quality gates. All PRD documents MUST conform to these standards. Reviewers MUST verify compliance before approving PRD changes.

***

## Spec Semantics: Normative vs Informative (Normative)

Every PRD statement MUST be one of:

* **Normative**: A testable requirement. Uses RFC 2119 keywords: **MUST**, **SHALL**, **MUST NOT**, **SHALL NOT**, **REQUIRED**.
* **Informative**: Background, rationale, examples, or design context. Uses: **MAY**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **OPTIONAL**.

### Rules

1. **MUST/SHALL/MUST NOT** MAY appear ONLY in sections explicitly tagged **\[Normative]** or **(Normative)** in the heading.
2. Sections without a normative/informative tag are **informative by default**.
3. Examples MUST be tagged **\[Example]** and MUST NOT introduce new requirements.
4. Rationale paragraphs (explaining *why* a requirement exists) are informative even when they appear inside a normative section.
5. Tables inside normative sections are normative unless the table caption or surrounding text marks them otherwise.

### Feature Completeness Rule

Any feature referenced in a user journey MUST have:

1. A contract specification (if on-chain) in the appropriate `06-contracts.md` or equivalent
2. A tool/SDK specification in the appropriate `07-sdk.md` or `08-mcp-tools.md`
3. Acceptance tests defined in `17-testing.md` or the domain's testing/milestones file

If any of these are missing, the feature MUST be explicitly marked **\[Deferred]** with a target phase.

***

## Document Types (Normative)

Every file in the `prd/` tree falls into one of three categories:

| Type    | Purpose                                                 | Content Rules                                                                      |
| ------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **PRD** | Product requirements and acceptance criteria            | Contains normative sections. Defines what MUST be built.                           |
| **OPS** | Deployment, runbooks, and operational procedures        | Informative. Describes how to deploy and operate. Not binding on product behavior. |
| **REF** | Reference material, glossary, market context, citations | Informative. Provides context and shared definitions.                              |

### Classification

| File                                                                | Type |
| ------------------------------------------------------------------- | ---- |
| `mcp-server/01-overview.md` through `mcp-server/13-distribution.md` | PRD  |
| `mcp-server/14-deployment.md`                                       | OPS  |
| `mcp-server/15-install-wizard.md`                                   | OPS  |
| `agents/*.md`                                                       | PRD  |
| `skills/*.md`                                                       | PRD  |
| `vault/00-quickstart.md` through `vault/16-synergies.md`            | PRD  |
| `vault/17-testing.md`                                               | PRD  |
| `vault/18-deployment.md`                                            | OPS  |
| `vault/19-threat-model.md`                                          | PRD  |
| `vault/DECISIONS.md`                                                | REF  |
| `vault/IMPLEMENTATION-STATE.md`                                     | REF  |
| `vault/research-citations.md`                                       | REF  |
| `shared/*.md`                                                       | REF  |
| `devenv/*.md`                                                       | PRD  |
| `devenv/README.md`                                                  | PRD  |
| `monorepo/01-overview.md` through `monorepo/09-implementation.md`   | PRD  |
| `monorepo/10-appendix.md`                                           | REF  |
| `monorepo/README.md`                                                | PRD  |
| `shared/package-registry.md`                                        | REF  |
| `shared/port-allocation.md`                                         | REF  |
| `shared/devenv-integration.md`                                      | REF  |
| `shared/user-journeys.md`                                           | REF  |
| `shared/doc-standards.md` (this file)                               | PRD  |

OPS files SHOULD include `> **Document Type**: OPS (informative)` in their header to make the distinction visible to readers.

***

## Doc Linter Checklist

A PRD change is not complete unless the following checks pass. These checks can be automated as a CI lint step.

### Semantic Checks

* [ ] No `MUST`, `SHALL`, or `MUST NOT` appears outside a `[Normative]` or `(Normative)` section
* [ ] No `[Example]` section introduces new requirements (no MUST/SHALL inside examples)
* [ ] Every feature referenced in a user journey has a contract spec, tool/SDK spec, and acceptance test -- or is marked `[Deferred]`

### Completeness Checks

* [ ] No references to undefined modules, tools, or contracts (every cross-reference resolves to a real section)
* [ ] No `TBD` entries in the chain capability tables for chains marked as "supported" (TBD is only valid for chains not yet confirmed)
* [ ] Every user journey step references a tool, contract spec, or SDK method

### Structural Checks

* [ ] Every file has a `> **Part of**:` or `> **Last Updated**:` header
* [ ] Every normative section includes at least one testable statement
* [ ] Cross-references use relative markdown links, not absolute URLs to generated files
* [ ] Document type classification in this file includes all `prd/` files

***

## Review Gate Integration

The existing [Review Gate](/docs/prd-product-requirements/prd.md) requirements are extended with doc standards verification:

1. Both sides of the canonical map are updated (requirements + implementation docs)
2. **Doc standards checklist passes** (this file)
3. If the change affects vault, `IMPLEMENTATION-STATE.md` is updated
4. If the change affects AI assets, mirrors are regenerated and drift check passes
5. Links in canonical index files are verified