docs(P03): complete domain-derived-docs phase

2026-08-05 00:30:31 +00:00
parent 2c15282ad4
commit 530ce3efed
27 changed files with 1556 additions and 0 deletions
@@ -0,0 +1,83 @@
+# Doc Templates — Derived Rules
+
+> Derives from `domains/documentation/first-principles.md` P7 (Structure), P2 (Audience Awareness), P3 (Examples are Mandatory).
+
+## Document Structure (P7)
+
+Every framework document follows a consistent structure:
+
+```
+# <Title>
+
+> One-line purpose. Who reads this and when.
+
+## 1. Manifesto (or Introduction)
+Why this document exists. The core belief.
+
+## 2. The Principles (or Rules)
+The numbered, named, derivable rules. Each rule has:
+- A name (P1, P2, ...)
+- A one-line definition
+- A "what it means" paragraph
+- A "what violates it" entry
+
+## 3. Conflict Resolution (for first-principles docs)
+Precedence among the rules. Non-tradeable declarations.
+
+## 4. What Violates These Principles
+A table of violations and the principle they breach.
+
+## 5. Relationship to Core
+Derivation link. See `matrix/principles-matrix.md`.
+```
+
+- The structure is the contract. A reader can scan any framework doc and find the same sections.
+- Derived (topic) docs simplify: drop §3, replace §5 with "Derives from `<domain>/first-principles.md`."
+
+## Audience Templates (P2)
+
+### For Agents
+- Lead with what to check before completing a task.
+- Bullet lists, not paragraphs.
+- "Run this checklist" framing.
+
+### For Humans (Onboarding)
+- Lead with what this is and who it's for.
+- Reading order. Quickstart.
+- Conversational tone, not terse.
+
+### For Humans (Reference)
+- Lead with the rules, indexed.
+- Tables for lookup.
+- Cross-references to other docs.
+
+## Example Template (P3 Examples are Mandatory)
+
+Every rule includes an example. The template:
+
+```
+### P<n>. <Name>
+<one-line definition>
+
+<what it means>
+
+Good:
+<example>
+
+Bad:
+<counter-example> (violates P<n>)
+```
+
+- The "good" example is realistic, not a strawman.
+- The "bad" example cites the principle it violates.
+- Examples are code, not prose. Show, don't tell.
+
+## What Violates Doc Templates
+
+| Violation | Principle |
+|-----------|-----------|
+| A doc with no examples | P3 Examples are Mandatory |
+| A first-principles doc with no "what violates" table | P7 Structure |
+| A doc that does not link to its core derivation | P5 Discoverability |
+| Inconsistent structure across domain docs | P7 |
+| A doc with no audience statement | P2 Audience Awareness |