add-doc-schemas

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>, RCPT-<command>) use fixed or slug-based IDs — see individual schemas in the category files. QA validation reports use a per-scope sequence ID (<feature-id>-qa-validation-NNN, not a global prefix) — see qa-validation in references/review.md and {{skill:add-id-convention/SKILL.md}}.

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):

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

Frontmatter:

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 change branch: once set — /add.new decides it; build-setup.sh executes it.
• 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):

---
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, qa-validation
history	references/history.md	changelog
product	references/product.md	owner, product
strategy	references/strategy.md	prd
marketing	references/marketing.md	saas-copy, landing-page
receipt	references/receipt.md	setup-receipt

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.

## 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 `[]`)
   - **`feature-about` only** — `branch:` present, matches `^[a-z]+/[0-9]{4}[A-Z]-[a-z0-9-]+$`, and its post-`/` slug equals the docs dir name (Hard Invariant). Legacy docs predating this field: **warn**, do not FAIL.
   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.