feat: add 'Explaining and Teaching' contract

[raifdmueller]

Adds a new semantic contract (not an anchor) to the /contracts page — the 17th entry in contracts.json, a sibling of Simple Explanation (ELI5) and Concise Response (TLDR).

What it is

A gated teaching loop for explain… / why… / how does … work requests: the goal is to explain and verify the learner understood, not just deliver an answer.

It composes six anchors that already live in the catalog, each on its own axis:

• 4MAT — sequence (Why → What → How → What-If)
• Programming as Theory Building (Naur) — the why: reasoning, trade-offs, branches not taken
• Socratic Method — diagnose first; questions, not answers
• Feynman Technique — explain-it-back as the sharpest check
• Bloom's Taxonomy — defines "understood" as Apply/Analyze, not recall
• Definition of Done — a written checklist, demonstrated rather than nodded at

The control flow no single anchor carries — gate each step, verify by active recall, stop when the checklist is met — is the contract's own contribution, and it scales to the size of the question (a quick "why is it named that?" gets one check, not a multi-stage session).

Changes

• website/public/data/contracts.json — new explaining-teaching entry (EN + DE template, all six anchor refs resolve)
• docs/changelog.adoc — New contracts entry under 2026-06-02

Notes

• contracts.html is a build artifact (gitignored); render-contracts.js already includes the new contract.
• Triggers are English-only (the German trigger phrases from the draft were dropped); a German templateDe is provided for the bilingual UI.
• 98/98 unit tests pass.

Summary by CodeRabbit

Release Notes

• New Features

  • Neue "Explaining and Teaching" Contract-Vorlage hinzugefügt, die bewährte Lehr- und Erklärungsmethoden integriert.

• Documentation

  • Changelog und Vorlagen-Katalog mit neuen Contract-Einträgen erweitert.

[coderabbitai]

Walkthrough

Ein neuer Semantic Contract „Explaining and Teaching" wird dokumentiert. Der Changelog-Eintrag beschreibt einen strukturierten Teaching-Ansatz kombiniert aus 4MAT, Socratic Method und Bloom's Taxonomy. Der Contract wird in die Contracts-Datendatei mit vollständigen Vorlagen in Englisch und Deutsch integriert.

Changes

Explaining and Teaching Contract

Layer / File(s)

Summary

Contract-Dokumentation und Dateneintrag docs/changelog.adoc, website/public/data/contracts.json

Der Changelog dokumentiert einen neuen Communication-Contract mit einer geführten Teaching-Loop für explain/why/how-Anfragen unter Nutzung von 4MAT, Programming as Theory Building, Socratic Method, Feynman Technique und Bloom's Taxonomy. Der Contract wird in der JSON-Datei mit ID explaining-teaching eingetragen, inklusive kategorialer Zuordnung als communication, lokalisierten Titeln und Beschreibungen sowie Anker-Referenzen und vollständigen Template-Texten.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• LLM-Coding/Semantic-Anchors#367: Erweitert ebenfalls website/public/data/contracts.json mit neuen Communication-Contract-Einträgen (concise-response, simple-explanation).
• LLM-Coding/Semantic-Anchors#375: Fügt weitere Semantic-Contract-Einträge in website/public/data/contracts.json ein (z. B. writing-style).
• LLM-Coding/Semantic-Anchors#366: Implementiert die Contracts-Datenseite und fetchContractsData()-Pipeline, die diese neuen Contract-Einträge zur Anzeige und zum Download nutzt.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Der PR-Titel beschreibt präzise die Hauptänderung: Hinzufügen eines neuen 'Explaining and Teaching'-Contracts. Dies entspricht genau den Änderungen in contracts.json und changelog.adoc.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

website/public/data/contracts.json (1)

191-192: ⚡ Quick win

Template in darstellbare Schritte aufteilen.

website/src/components/contracts-page.js:94-142 und scripts/render-contracts.js:30-87 formatieren template zeilenweise und erkennen nur mit - beginnende Zeilen als Listenpunkte. In der aktuellen Fassung werden template und templateDe daher als je ein großer Textblock ausgegeben, obwohl der Contract selbst eine Sequenz und Checkliste beschreibt. Bitte in Absätze und - -Punkte umbrechen, damit Kartenansicht, contracts.html und llms.txt besser lesbar bleiben.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@website/public/data/contracts.json` around lines 191 - 192, The templates are
rendered as single blocks because the renderer in scripts/render-contracts.js
(the function that serializes contract.template/ templateDe) and the consumer in
website/src/components/contracts-page.js (ContractsPage/renderContract or
equivalent) only treat existing "- " lines as list items; update the serializer
to split template/templateDe into paragraphs (split on double newlines) and into
list lines by breaking long sentences/clauses into separate lines prefixed with
"- " where the text reads like checklist steps (e.g., sentence boundaries,
semicolons, "After each", "Keep a running", "Diagnose first", etc.), then have
contracts-page.js use those newline-delimited paragraphs and "- " markers to
render <p> and <li> properly and ensure scripts/render-contracts.js writes the
same formatted output for contracts.html and llms.txt so cards, HTML, and text
outputs show paragraphs and checklist bullets instead of one big paragraph.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@website/public/data/contracts.json`:
- Around line 191-192: The templates are rendered as single blocks because the
renderer in scripts/render-contracts.js (the function that serializes
contract.template/ templateDe) and the consumer in
website/src/components/contracts-page.js (ContractsPage/renderContract or
equivalent) only treat existing "- " lines as list items; update the serializer
to split template/templateDe into paragraphs (split on double newlines) and into
list lines by breaking long sentences/clauses into separate lines prefixed with
"- " where the text reads like checklist steps (e.g., sentence boundaries,
semicolons, "After each", "Keep a running", "Diagnose first", etc.), then have
contracts-page.js use those newline-delimited paragraphs and "- " markers to
render <p> and <li> properly and ensure scripts/render-contracts.js writes the
same formatted output for contracts.html and llms.txt so cards, HTML, and text
outputs show paragraphs and checklist bullets instead of one big paragraph.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 535bf146-63a5-4fdd-a4dd-8cf067187e2f

📥 Commits

Reviewing files that changed from the base of the PR and between a6af814 and 5982f3c.

📒 Files selected for processing (2)

• docs/changelog.adoc
• website/public/data/contracts.json