---
name: add-doc-schemas
description: Source of truth for ADD doc rules, depth floors, IDs, refs, validation gate. Load before any doc write.
---

# Documentation Schemas & Standards

## Overview

Single source of truth for every documentation asset generated by ADD commands. This `SKILL.md` carries the universal content — output-length doctrine, voice principles, language rules, formatting rules, cache discipline, ID convention, validation gate. Schemas live in `references/<category>.md`, organized by **doc purpose** rather than by producing command. Commands load this skill once and resolve their schema via the Schema Index by Category below.

## When to Use

- Writing or refactoring a command that creates/updates a doc asset consumed by agents
- Generating any agent-consumed doc — feature about/plan/design/brainstorm, hotfix docs, changelog, owner/product, audit/diagnose reports, saas-copy, landing-page, PRD, or any future doc kind
- Validating an existing doc against its schema (via the gate block below)
- Cross-linking docs via `{{doc:ID}}` syntax

## When NOT to Use

- Free-form drafts or scratch notes
- External docs, vendor READMEs, third-party specs
- Commit messages, PR bodies (see `add-commit`)
- Command/skill/script path references — use `{{cmd:}}` / `{{skill:}}` per `{{skill:add-resource-path-convention/SKILL.md}}`
- `tasks.md` — owned by `{{skill:add-tasks-checklist/SKILL.md}}`

## Output Length Doctrine

Agent-generated documentation has no character or word limit. Length is governed by **depth floors** and **density**; numeric advisories (`<200 words`, etc.) are prohibited in any rule constraining agent output.

1. **Completeness beats brevity.** A section is done when someone can act on it without follow-up questions. A missing fact is a worse failure than a long section.
2. **Density beats length.** Every sentence earns its place. No filler, no restating the heading, no narrative that could be a bullet.

**Platform-imposed limits stay** (Anthropic SDK `name ≤64`, `description ≤1024`, slug/branch identifier shapes) — external constraints, not framework opinions on density.

## Universal Rules

Schema-agnostic rules that apply to every generated doc, even when the schema is silent.

### Voice

- **Extractive only.** No abstractive summarization. Allowed forms: tables, bullet lists, minified JSON, topic sentences, factual bullets. Prohibited: narrative paraphrase of source material.
- **Clarity on what and why.** Every statement carries a fact, a constraint, a decision, a link, or an observable signal — never filler.
- **No aspirational language.** No *futuramente*, *idealmente*, *pretendemos*, "in a future version", "we plan to". Extractive docs describe what is, not what might be.
- **No marketing copy, no superlatives, no unverified claims.** Schemas that genuinely need persuasive copy (saas-copy, landing-page) declare it explicitly; everywhere else, plain factual voice.

### Language

| Context | Language |
|---|---|
| Prose, explanations, rationale | Follow the `language` field in `owner.md` (e.g. `pt-br`, `en-us`); default to English when the field is unset or `owner.md` does not exist |
| Code, git, CLI flags, technical terms | English |
| Frontmatter keys and schema type names | English (machine-parsed) |

Technical terms (commit, branch, frontmatter, chunk, schema, hook) stay in English regardless of the owner's language setting. Do not translate them.

### Markdown Formatting

- **JSON = DATA. Markdown = INSTRUCTIONS.** Minified JSON is exclusively for structured data the agent looks up (configs, tech stack, path mappings, dep lists). Rules, instructions, orientation, constraints, and behavioral guidance MUST use markdown (lists, tables, prose). Never put rules inside JSON objects. See `{{skill:add-token-efficiency/SKILL.md}}` for compression patterns.
- **Headers:** no emojis, no decorative characters, no ASCII art. H1 is reserved for the doc title or schema type — never repeat.
- **Code fences:** always tagged with a language (` ```bash `, ` ```json `, ` ```yaml `). Untagged fences break agent parsing.
- **Tables:** use when you have ≥3 items with the same shape. Below 3, use bullets. Tables suit mappings that orient behavior (decisions, risks, scope rules).
- **Inline code >10 lines:** avoid — link to the file with `path:line` instead. Exception: the snippet IS the content (schema examples, exact config values) and cannot be linked.
- **Single line breaks** between sections. No triple blank lines. No horizontal rules as decoration.

### Cache Documental (MANDATORY)

Every write to an existing doc MUST follow: **read → preserve → complement → bump `updated:`**. Never overwrite blind.

| Situation | Action |
|---|---|
| Doc does not exist | Create from schema + set `created:` + `updated:` |
| Doc exists, template-empty | Fill sections + bump `updated:` |
| Doc exists, populated | Read → complement → bump `updated:` |
| Conflicting info | New info wins; log change in-section |

Anti-patterns: recreating a doc from scratch; silently overwriting populated sections; forgetting to bump `updated:`; duplicating content already owned by another doc (link instead).

## ID Convention & References

Docs reference each other via **stable IDs** (`F0042`, `H0013`, `PRD0009`, `CHG0001`) rather than paths or titles. References use `{{doc:<ID>}}` syntax and are resolved at **runtime** by agents via grep on frontmatter `id:` — NOT at build time.

Contrast with build-time variables: `{{cmd:}}` / `{{skill:}}` are resolved by `build.js` during provider build. `{{doc:ID}}` passes through build untouched. `build.js` MUST NOT be extended to resolve `{{doc:}}`.

### ID Prefixes

Every ADD doc type that participates in the reference graph has a prefix. IDs are **global within their prefix** and zero-padded to 4 digits.

| Letter | Type | Format | Example | Allocator |
|---|---|---|---|---|
| `F` | Feature | `[NNNN]F` | `0042F` | `/add.new` |
| `H` | Hotfix | `[NNNN]H` | `0013H` | `/add.hotfix` |
| `PRD` | PRD (framework strategy) | `PRD[NNNN]` | `PRD0009` | `/add.plan` (framework mode) |
| `CHG` | Changelog entry | `CHG[NNNN]` | `CHG0001` | `/add.done` |

> **Convention:** Feature/hotfix IDs use `[NNNN][L]` (number first, letter suffix) per `{{skill:add-id-convention/SKILL.md}}`. `PRD` and `CHG` are separate namespaces with no letter suffix.

Other doc types (`OWNER`, `PRODUCT`, `AUDIT-<date>`, `DIAG-<slug>`, `COPY-<slug>`, `LAND-<slug>`, `BRN-<slug>`) use fixed or slug-based IDs — see individual schemas in the category files.

### ID Allocation

IDs are allocated **manually** per prefix, monotonically increasing. Before creating a new doc, grep the counter: `grep -rhE "^id: F[0-9]{4}$" docs/ | sort -u | tail -1`. Use next integer, zero-padded. Never reuse an ID even if the doc is deleted.

### Reference Syntax

Body text uses `{{doc:<ID>}}` so agents distinguish refs from incidental text. Frontmatter `related:` is a YAML list of bare IDs (no wrapping).

**Inline (body):**

```markdown
See {{doc:F0042}} for the feature scope.
The regression was introduced by {{doc:H0013}}.
```

**Frontmatter:**

```yaml
related: [F0042, PRD0009, H0013]
```

**Resolution.** When an agent encounters `{{doc:F0042}}`: (1) `grep -rE "^id: F0042$" docs/`, (2) resolve to file path, (3) read target (frontmatter + TL;DR first, sections on demand).

**Orphans.** A `{{doc:<ID>}}` whose target does not resolve is a **warning**, not error — the gate surfaces it; user decides. Deleting a doc does NOT fix inbound refs — prefer `status: deprecated` over deletion.

### Edit Discipline

- Always bump `updated:` on any edit.
- Optionally set `by:` to signal the editor.
- Never change `id:` once allocated. If the doc fundamentally changes type, create a new doc with a new ID.
- Never edit `related:` to hide a broken link.

## Universal Document Requirements

Every schema inherits these rules. Do NOT override unless the schema explicitly relaxes them.

**Frontmatter — mandatory fields (YAML):**

```yaml
---
id: <PREFIX><NNNN>        # per ID Convention section above
type: <schema-type>       # one of the schemas in references/<category>.md
created: YYYY-MM-DD
updated: YYYY-MM-DD
related: []               # list of doc IDs this doc depends on or references
---
```

Optional: `by:` (last editor — human or agent identifier), `status:`, `slug:`.

**Body requirements:**

- **TL;DR** — H2 `## TL;DR` immediately after frontmatter. Conveys: what the doc is, why it exists, headline outcome/decision. Extractive. Stops when those three are covered. No length number applies.
- **TOC** — required when the doc has >3 H2 sections. Flat bullet list linking anchors. Placed right after TL;DR.
- **Section chunks** — each H2/H3 body opens with a topic sentence (the grep target). Each chunk = topic sentence + extractive content. Split by sub-heading rather than truncate when one chunk grows past a natural boundary. No length number applies.
- **Refs** — doc→doc links MUST use `{{doc:<ID>}}` syntax. Command/skill refs use `{{cmd:}}` / `{{skill:}}` per `{{skill:add-resource-path-convention/SKILL.md}}`.
- **Metadata** — frontmatter IS the metadata; bump `updated:` per Cache Documental.

## Schema Index by Category

Schemas are grouped by **doc purpose**, not by producing command. Each category file owns its schemas plus the section-shape conventions and notation rules shared by them. Commands resolve their schema by name — the category file holding it is below.

| Category | File | Schemas |
|----------|------|---------|
| `new-feature` | `references/new-feature.md` | feature-about, feature-plan, feature-design, brainstorm |
| `fix` | `references/fix.md` | hotfix-about, hotfix-related |
| `review` | `references/review.md` | audit-report, diagnose-report |
| `history` | `references/history.md` | changelog |
| `product` | `references/product.md` | owner, product |
| `strategy` | `references/strategy.md` | prd |
| `marketing` | `references/marketing.md` | saas-copy, landing-page |

**Loading discipline.** A command that produces, say, a `feature-about` loads this `SKILL.md` (universal rules + ID + gate) plus `references/new-feature.md` (its category). It does NOT load every category file — JIT by category.

**Schema name → category lookup.** Use the table above. Adding a new schema = (1) place it in the right category file, (2) update this table, (3) if a new ID prefix is needed, add it to the ID Prefixes table.

## Validation Gate Block

Every generator command MUST paste the following block as **the final STEP that operates on the doc** — i.e. after every step that writes, edits, or transforms the doc, and before any post-doc step (completion summary, fresh-reader review via `add-doc-reviewer`, next-step routing, merge execution, iteration logging). Steps that do not modify the gated doc may follow the gate. The block is self-contained and imperative. Replace `<SCHEMA>` with the schema type in use.

```markdown
## STEP N: Validation Gate (add-doc-schemas)

Run these checks against the doc you just wrote. DO NOT skip. DO NOT mark the command complete until every check passes or warns.

1. **Frontmatter presence.** Grep `^---$` at line 1. Confirm YAML block closes. Required fields for `<SCHEMA>`:
   - `id:` matches the prefix rule in the ID Convention section of this skill
   - `type: <SCHEMA>` exact match
   - `created:` and `updated:` are ISO dates (YYYY-MM-DD)
   - `related:` is a YAML list (may be empty `[]`)
   If any field is missing: STOP. Fix the doc. Re-run this gate.

2. **TL;DR present and complete.** Grep `^## TL;DR$`. The body MUST convey: what the doc is, why it exists, and the headline outcome/decision. If any is missing: rewrite extractively — do NOT summarize abstractively, do NOT shrink by dropping the headline.

3. **TOC rule.** Count H2 sections (`^## `). If >3 and no `## TOC` / anchor list right after TL;DR: add it. Flat bullets only.

4. **Depth floors met.** For each H2/H3 in the schema, walk the schema's depth-floor list and confirm every required fact is present in the chunk. A section that looks clean but omits required facts is INCOMPLETE. If a floor is unmet: add the missing content. If a fact is genuinely unknowable, write `unknown — <why>` rather than omit.

5. **Non-redundancy / density.** Apply Universal Rules → Voice: every sentence is fact, decision, constraint, link, or signal — never filler. Delete restatements, paraphrase, repetition. Numeric length caps are prohibited.

6. **Doc refs resolve.** For every `{{doc:<ID>}}` in the doc, run reverse grep: `grep -rE "^id: <ID>$" docs/`. Each ref MUST return ≥1 hit. Unresolved refs = WARNING (not error); print them in the command output for the user to fix.

7. **Hard bans absent.** Confirm none of the schema's "Hard bans" items are present (emojis in headers, ASCII art where forbidden, aspirational language, abstractive paraphrase, forbidden content types).

8. **Metadata footer.** Confirm `updated:` in frontmatter matches today's date. If editing an existing doc, confirm original `created:` was preserved.

DO NOT use abstractive summarization to trim a section — summarization loses information the depth floor requires. DO NOT delete required content to make the gate pass — split into linked docs instead, or mark items `unknown — <why>`. DO NOT silently drop unresolved refs — surface them as warnings. DO NOT introduce numeric length caps (e.g. `<200 words`, `~100-150 words`) anywhere in the doc body.

Output at end:
- `gate: PASS` or `gate: FAIL`
- list of warnings (orphan refs, `unknown` markers)
- list of fixes applied (if any)
```

## Self-Governance

This skill is itself at risk of becoming unmaintainable. Rules:

- **One category = one file under `references/`.** Adding a schema goes into the right category file, not into a new top-level file. If a schema does not fit any existing category, evaluate creating a new category (and update the Schema Index).
- **No inline examples of full docs.** Reference by `{{doc:}}` to a canonical example when the example exceeds a small snippet.
- **Changes to the schema registry are breaking by default.** Bump the framework version and list affected commands.
- **Audit trigger:** if `SKILL.md` or any category file exceeds 900 lines, run `/add.audit` on this skill and split.

## Cross-references

- `{{skill:add-token-efficiency/SKILL.md}}` — generic compression patterns for authoring commands/skills (compression patterns only; output length is governed here)
- `{{skill:add-resource-path-convention/SKILL.md}}` — build-time resource refs (`{{cmd:}}` / `{{skill:}}`)
- `{{skill:add-tasks-checklist/SKILL.md}}` — `tasks.md` schema (sibling, not absorbed here)
- `{{skill:add-doc-reviewer/SKILL.md}}` — cold-read sanity-check skill; receives `schema_name` and resolves via the Schema Index above
- `{{skill:add-claude-md-style/SKILL.md}}` — CLAUDE.md generation rules (separate pipeline)
- `{{doc:PRD0009}}` — Documentation Context Engineering (originating PRD)
- `{{doc:PRD0012}}` — Doc Skills Consolidation
- `{{doc:PRD0019}}` — Documentation Standards Refactor (current structure: schemas by category, no length caps)

---

> **Migration note (2026-05-09, PRD0019):** Length authority extended to all agent-generated docs — advisory caps removed, depth floors and density are the universal rule. Schemas reorganized by purpose category in `references/<category>.md`. `business.md` and `technical.md` deleted; their voice principles moved to this `SKILL.md` (Universal Rules), schema-specific notation moved to the relevant category file, and JSON/compression discipline already lived in `add-token-efficiency`.