Merge pull request #375 from raifdmueller/feat/writing-style-contract

feat: add Writing Style semantic contract

Author: rdmueller

docs/rejected-proposals.adoc

@@ -23,18 +23,36 @@ A real methodology but too specialized for reliable activation across different
 
 | *TLDR*
 | Structurally unsuitable
-| Underspecified instruction with no defined structure. Just means "be brief" without any framework for how. Not a methodology.
+| Underspecified instruction with no defined structure. Just means "be brief" without any framework for how. Not a methodology. +
+*Now available as link:#/contracts[Semantic Contract]*: "Concise Response" — composes BLUF + Strunk & White.
 
 | *ELI5* (Explain Like I'm 5)
 | Structurally unsuitable
-| Vague target level with no pedagogical framework. No consistent interpretation of what "5-year-old level" means technically.
+| Vague target level with no pedagogical framework. No consistent interpretation of what "5-year-old level" means technically. +
+*Now available as link:#/contracts[Semantic Contract]*: "Simple Explanation" — composes Feynman Technique.
+
+| *Spec-Driven Development* (https://github.com/LLM-Coding/Semantic-Anchors/pull/356[#356])
+| Structurally unsuitable
+| Relevant concept but no single canonical definition — different people mean different things (API-first, formal specs, our workflow). Not attributable to a specific proponent. +
+*Now available as link:#/contracts[Semantic Contracts]*: "Specification" + "Requirements Discovery" — composes Gherkin, BDD, Socratic Method, MECE, PRD.
+
+| *Explicit Contract Surface* (https://github.com/LLM-Coding/Semantic-Anchors/pull/357[#357])
+| Structurally unsuitable
+| Well-described design practice but not an established term in the literature. Combines existing anchors (Clean Architecture, Hexagonal, DDD, SOLID DIP/ISP) without adding new activation. +
+*Now available as link:#/contracts[Semantic Contract]*: "Layer Boundaries".
 
 | *MIRRR UX Framework* (https://github.com/LLM-Coding/Semantic-Anchors/issues/150[#150])
 | Not in training data
 | A real UX framework with defined methodology, but not widely enough documented for LLMs to reliably recognize it and activate the correct concepts.
 
 |===
 
+[TIP]
+====
+Terms that don't qualify as semantic anchors can still be useful as link:#/contracts[Semantic Contracts].
+A contract defines what a term means in your project — either by composing established anchors or by providing custom definitions that only exist within your team.
+====
+
 == How We Evaluate
 
 Every proposal is tested against our four quality criteria:

docs/rejected-proposals.de.adoc

@@ -23,18 +23,36 @@ Eine echte Methodik, aber zu spezialisiert für zuverlässige Aktivierung über
 
 | *TLDR*
 | Strukturell ungeeignet
-| Unterspezifizierte Anweisung ohne definierte Struktur. Bedeutet nur "fasse dich kurz" ohne ein Framework dafür. Keine Methodik.
+| Unterspezifizierte Anweisung ohne definierte Struktur. Bedeutet nur "fasse dich kurz" ohne ein Framework dafür. Keine Methodik. +
+*Jetzt verfügbar als link:#/contracts[Semantic Contract]*: "Concise Response" — kombiniert BLUF + Strunk & White.
 
 | *ELI5* (Explain Like I'm 5)
 | Strukturell ungeeignet
-| Vages Zielniveau ohne pädagogisches Framework. Keine konsistente Interpretation dessen, was "Niveau eines 5-Jährigen" technisch bedeutet.
+| Vages Zielniveau ohne pädagogisches Framework. Keine konsistente Interpretation dessen, was "Niveau eines 5-Jährigen" technisch bedeutet. +
+*Jetzt verfügbar als link:#/contracts[Semantic Contract]*: "Simple Explanation" — nutzt die Feynman-Technik.
+
+| *Spec-Driven Development* (https://github.com/LLM-Coding/Semantic-Anchors/pull/356[#356])
+| Strukturell ungeeignet
+| Relevantes Konzept, aber keine einheitliche Definition — verschiedene Interpretationen (API-first, formale Specs, unser Workflow). Nicht einem konkreten Urheber zuordenbar. +
+*Jetzt verfügbar als link:#/contracts[Semantic Contracts]*: "Specification" + "Requirements Discovery" — kombiniert Gherkin, BDD, Sokratische Methode, MECE, PRD.
+
+| *Explicit Contract Surface* (https://github.com/LLM-Coding/Semantic-Anchors/pull/357[#357])
+| Strukturell ungeeignet
+| Gut beschriebene Design-Praxis, aber kein etablierter Begriff in der Literatur. Kombiniert bestehende Anker (Clean Architecture, Hexagonal, DDD, SOLID DIP/ISP) ohne neue Aktivierung. +
+*Jetzt verfügbar als link:#/contracts[Semantic Contract]*: "Layer Boundaries".
 
 | *MIRRR UX Framework* (https://github.com/LLM-Coding/Semantic-Anchors/issues/150[#150])
 | Nicht in Trainingsdaten
 | Ein echtes UX-Framework mit definierter Methodik, aber nicht weit genug dokumentiert, damit LLMs es zuverlässig erkennen und die richtigen Konzepte aktivieren.
 
 |===
 
+[TIP]
+====
+Begriffe, die nicht als Semantic Anchors qualifizieren, können trotzdem als link:#/contracts[Semantic Contracts] nützlich sein.
+Ein Contract definiert, was ein Begriff in deinem Projekt bedeutet — entweder durch Komposition etablierter Anker oder durch eigene Definitionen, die nur in deinem Team existieren.
+====
+
 == Wie wir bewerten
 
 Jeder Vorschlag wird gegen unsere vier Qualitätskriterien getestet:

scripts/generate-llms-txt.js

@@ -249,19 +249,11 @@ function generateLlmsTxt() {
       lines.push('')
       lines.push('# Semantic Contracts')
       lines.push('')
-      lines.push(
-        'Semantic Contracts define what a term means in your project — either by'
-      )
-      lines.push(
-        'composing established anchors or by providing custom definitions that only'
-      )
+      lines.push('Semantic Contracts define what a term means in your project — either by')
+      lines.push('composing established anchors or by providing custom definitions that only')
       lines.push('exist within your team.')
-      lines.push(
-        'Add them to your AGENTS.md or CLAUDE.md.'
-      )
-      lines.push(
-        'Select and download: https://llm-coding.github.io/Semantic-Anchors/#/contracts'
-      )
+      lines.push('Add them to your AGENTS.md or CLAUDE.md.')
+      lines.push('Select and download: https://llm-coding.github.io/Semantic-Anchors/#/contracts')
       lines.push('')
 
       for (const contract of contracts) {
@@ -276,9 +268,7 @@ function generateLlmsTxt() {
       }
 
       lines.push('---')
-      console.warn(
-        `  Including ${contracts.length} Semantic Contracts in llms.txt`
-      )
+      console.warn(`  Including ${contracts.length} Semantic Contracts in llms.txt`)
     }
   } catch {
     // contracts.json not found — skip

website/public/data/contracts.json

@@ -119,5 +119,16 @@
     "template": "Explain complex concepts using simple language and everyday analogies. When the explanation feels hard to write, that reveals gaps in understanding — study those areas first (Feynman Technique).",
     "templateDe": "Komplexe Konzepte mit einfacher Sprache und Alltagsanalogien erklären. Wenn die Erklärung schwerfällt, zeigt das Wissenslücken — diese zuerst vertiefen (Feynman-Technik).",
     "category": "communication"
+  },
+  {
+    "id": "writing-style",
+    "title": "Writing Style",
+    "titleDe": "Schreibstil",
+    "description": "How we write technical texts — language, tone, and structure",
+    "descriptionDe": "Wie wir technische Texte schreiben — Sprache, Ton und Struktur",
+    "anchors": ["gutes-deutsch-wolf-schneider", "plain-english-strunk-white"],
+    "template": "Writing follows Gutes Deutsch nach Wolf Schneider (or Plain English according to Strunk & White).\n\nAdditionally:\n- Technical terms stay in English (LLM, Prompt, Token, Spec, etc.)\n- Address the reader directly, use first person sparingly but deliberately\n- Use analogies to human thinking to explain technical concepts\n- One thought per paragraph (5-8 sentences is fine)\n- Section headings are statements, not topic announcements\n- First sentence says what the paragraph is about\n- Show code and prompts, don't just claim things work\n- Conclusions make a clear statement — never end with 'it remains exciting'",
+    "templateDe": "Schreibstil folgt Gutes Deutsch nach Wolf Schneider (oder Plain English nach Strunk & White).\n\nZusätzlich:\n- Fachbegriffe auf Englisch lassen (LLM, Prompt, Token, Spec, etc.)\n- Leser direkt ansprechen, Ich-Perspektive sparsam aber gezielt\n- Analogien zum menschlichen Denken für technische Konzepte\n- Ein Gedanke pro Absatz (5-8 Sätze OK)\n- Zwischenüberschriften als Aussagen, nicht Themenankündigungen\n- Erster Satz sagt sofort worum es geht\n- Code/Prompts zeigen, nicht nur behaupten\n- Fazit: klare Aussage, kein 'es bleibt spannend'",
+    "category": "communication"
   }
 ]

website/tests/e2e/website.spec.js

@@ -24,7 +24,7 @@ test.describe('Homepage - Card Grid', () => {
     await expect(page.locator('#lang-toggle')).toHaveText('DE')
 
     // Check navigation links (use .first() to select desktop nav, not mobile)
-    await expect(page.locator('a[data-route="/"]').first()).toContainText('Catalog')
+    await expect(page.locator('a[data-route="/"]').first()).toContainText('Anchors')
     await expect(page.locator('a[data-route="/about"]').first()).toContainText('About')
     await expect(page.locator('a[data-route="/contributing"]').first()).toContainText('Contributing')
   })
@@ -157,6 +157,8 @@ test.describe('Homepage - Card Grid', () => {
   })
 
   test('should display action links', async ({ page }) => {
+    // About link is in the More dropdown — open it first
+    await page.locator('#more-menu-toggle').click()
     const aboutLink = page.locator('a[href="#/about"]').first()
     await expect(aboutLink).toBeVisible()
 
@@ -223,7 +225,8 @@ test.describe('Routing - Documentation Pages', () => {
   })
 
   test('should navigate to About page', async ({ page }) => {
-    // Click About link (use first for desktop nav)
+    // About is in the More dropdown — open it first
+    await page.locator('#more-menu-toggle').click()
     await page.locator('a[data-route="/about"]').first().click()
 
     // URL should update
@@ -239,7 +242,8 @@ test.describe('Routing - Documentation Pages', () => {
   })
 
   test('should navigate to Contributing page', async ({ page }) => {
-    // Click Contributing link (use first for desktop nav)
+    // Contributing is in the More dropdown — open it first
+    await page.locator('#more-menu-toggle').click()
     await page.locator('a[data-route="/contributing"]').first().click()
 
     // URL should update
@@ -254,11 +258,12 @@ test.describe('Routing - Documentation Pages', () => {
     await expect(contributingLink).toHaveClass(/font-semibold/)
   })
 
-  test('should navigate back to Catalog from About', async ({ page }) => {
-    // Go to About (use first for desktop nav)
+  test('should navigate back to Anchors from About', async ({ page }) => {
+    // Go to About via More dropdown
+    await page.locator('#more-menu-toggle').click()
     await page.locator('a[data-route="/about"]').first().click()
 
-    // Go back to Catalog
+    // Go back to Anchors
     await page.locator('a[data-route="/"]').first().click()
 
     // URL should be home
@@ -267,9 +272,9 @@ test.describe('Routing - Documentation Pages', () => {
     // Card grid should be visible
     await expect(page.locator('.anchor-card').first()).toBeVisible()
 
-    // Catalog link should be highlighted (use .first() to select desktop nav)
-    const catalogLink = page.locator('a[data-route="/"]').first()
-    await expect(catalogLink).toHaveClass(/font-semibold/)
+    // Anchors link should be highlighted (use .first() to select desktop nav)
+    const anchorsLink = page.locator('a[data-route="/"]').first()
+    await expect(anchorsLink).toHaveClass(/font-semibold/)
   })
 
   test('should handle direct URL to About page', async ({ page }) => {
@@ -282,7 +287,8 @@ test.describe('Routing - Documentation Pages', () => {
   })
 
   test('should handle browser back button', async ({ page }) => {
-    // Navigate to About (use first for desktop nav)
+    // Navigate to About via More dropdown
+    await page.locator('#more-menu-toggle').click()
     await page.locator('a[data-route="/about"]').first().click()
 
     // Go back