Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: add plain-language spec writing guidance (#5945)

Cindy Zhang70266189188a
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index a4c0e1def5..a1255733d0 100644
--- a/docs/architecture/knowledge-contracts.md
+++ b/docs/architecture/knowledge-contracts.md
@@ -112,6 +112,60 @@ Every record is either:
- **INV9 — Current records have no implicit precedence.** A newer, narrower, or
more local current record does not silently override another current record.
+## Writing specifications and contracts
+
+These rules guide writing. They do not permit semantic compaction. They come from
+directional evidence and project-owner judgment; the agent benchmark did not
+measure human readability, so this is not a quantified readability claim.
+
+- Use familiar words and short, direct sentences.
+- State each rule once, beside the conditions and exceptions that control it.
+- Use readable tables for branches or state matrices when they improve scanning.
+ Never remove contract content merely to shorten a record.
+
+Plain language must preserve normative force, predicates, cardinality, defaults,
+compatibility, authority, owners, IDs, evidence state, and decision status. Do not
+delete, weaken, merge, or hide distinct normative content. Replace a local fact
+with a link only when this record's ownership rules assign that fact to another
+canonical owner.
+
+Aim to keep a single specification record at or below 200 lines. This is a soft
+readability ceiling, not a schema rule, validation gate, deletion target, or
+reason to migrate accepted history. Exceed it when the full contract, exact
+conditions, evidence boundaries, decisions, or required template structure need
+more room. First remove true duplication, shorten prose without changing meaning,
+use readable tables or lists, and link genuinely shared authority as INV2
+requires. If the record still exceeds 200 lines, keep the content and explain why
+in pull-request review. Do not minify tables or paragraphs to game the count;
+human scanability wins.
+
+### Same rule, plainer form
+
+Dense:
+
+> When `items` contains exactly one visible item, the component MUST announce that
+> item exactly once; when `items` contains zero or more than one visible item, it
+> MUST NOT announce an item, and consumers that omit `items` MUST retain the
+> existing silent behavior.
+
+Plain:
+
+| Condition | Required behavior |
+| ----------------------------------- | --------------------------------------- |
+| `items` is omitted | MUST keep the existing silent behavior. |
+| Exactly one visible item is present | MUST announce that item exactly once. |
+| Zero or more than one is present | MUST NOT announce an item. |
+
+The plain version changes the shape, not the meaning.
+
+### Before review
+
+- [ ] Compare the edited text with its source and confirm that every contract
+ property named above remains explicit.
+- [ ] Confirm each rule appears once, with its conditions and exceptions beside it.
+- [ ] Confirm tables and lists improve scanning without hiding content; if the
+ record exceeds 200 lines, explain why it needs the extra space.
+
### When current records disagree
1. A draft is context only and cannot conflict with current policy.