From 2abc833ec92c99d6221746cabef9f36d51ddc00e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Fri, 27 Mar 2026 06:48:18 +0000 Subject: [PATCH 1/4] feat: add Writing Style contract Composes Wolf Schneider / Strunk & White with project-specific rules: - Technical terms stay English - Address reader directly - Headings as statements - Show code, don't just claim - Clear conclusions Example of a contract that extends anchors with custom team rules. Co-Authored-By: Claude Opus 4.6 (1M context) --- website/public/data/contracts.json | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/website/public/data/contracts.json b/website/public/data/contracts.json index 6894b93..d765abc 100644 --- a/website/public/data/contracts.json +++ b/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" } ] From ff259f1fef581edd6e4c12228642fb0b4bfe6ade Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Fri, 27 Mar 2026 06:57:06 +0000 Subject: [PATCH 2/4] =?UTF-8?q?docs:=20update=20rejected=20proposals=20?= =?UTF-8?q?=E2=80=94=20link=20to=20Semantic=20Contracts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - TLDR → now "Concise Response" contract (BLUF + Strunk & White) - ELI5 → now "Simple Explanation" contract (Feynman Technique) - Spec-Driven Development → now "Specification" + "Requirements Discovery" - Explicit Contract Surface → now "Layer Boundaries" contract - Added tip: rejected anchors can live on as Semantic Contracts Updated both EN and DE versions. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/rejected-proposals.adoc | 22 ++++++++++++++++++++-- docs/rejected-proposals.de.adoc | 22 ++++++++++++++++++++-- 2 files changed, 40 insertions(+), 4 deletions(-) diff --git a/docs/rejected-proposals.adoc b/docs/rejected-proposals.adoc index 2f3c157..744f0ce 100644 --- a/docs/rejected-proposals.adoc +++ b/docs/rejected-proposals.adoc @@ -23,11 +23,23 @@ 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 @@ -35,6 +47,12 @@ A real methodology but too specialized for reliable activation across different |=== +[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: diff --git a/docs/rejected-proposals.de.adoc b/docs/rejected-proposals.de.adoc index 7bbc895..8dee905 100644 --- a/docs/rejected-proposals.de.adoc +++ b/docs/rejected-proposals.de.adoc @@ -23,11 +23,23 @@ 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 @@ -35,6 +47,12 @@ Eine echte Methodik, aber zu spezialisiert für zuverlässige Aktivierung über |=== +[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: From cab04415115a60776c7857f5cf37b0e69ee9ad73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Fri, 27 Mar 2026 07:06:43 +0000 Subject: [PATCH 3/4] style: format generate-llms-txt.js with Prettier Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/generate-llms-txt.js | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/scripts/generate-llms-txt.js b/scripts/generate-llms-txt.js index 2031c8a..e561f01 100644 --- a/scripts/generate-llms-txt.js +++ b/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 From e14ead1479e5280ddfa1ac7534b7b3f555643838 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Fri, 27 Mar 2026 07:31:17 +0000 Subject: [PATCH 4/4] fix: update E2E tests for new navigation (Anchors + More dropdown) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - "Catalog" → "Anchors" in nav text assertion - About/Contributing tests now open More dropdown first - "navigate back to Catalog" → "navigate back to Anchors" Co-Authored-By: Claude Opus 4.6 (1M context) --- website/tests/e2e/website.spec.js | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/website/tests/e2e/website.spec.js b/website/tests/e2e/website.spec.js index 3b3f086..6c51387 100644 --- a/website/tests/e2e/website.spec.js +++ b/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