refine: sharpen the Explaining and Teaching contract

[raifdmueller]

Sharpens the Explaining and Teaching contract (contracts.json, EN + DE) without changing its anchors.

What changed

• Names the trigger ("explain / why / how") so the contract explicitly replaces the default "just explain" behaviour instead of merely describing it.
• Reorders to the real execution flow: ground yourself → frame the checklist → diagnose → teach one item in 4MAT order → verify → gate. Previously both "Sequence each unit (4MAT)" and "Diagnose first" claimed primacy, and the gate (the actual differentiator) was buried as the last bullet.
• Adds a grounding step: learn the current state before teaching — go to the source (the actual code, the spec, the docs), don't teach from stale memory.
• Adds two guardrails that the contract previously lacked: an over-fire brake (a one-line factual question gets a one-line answer, not a loop) and an explicit learner opt-out ("just tell me").
• Generalised away from code-only wording so it applies to any topic; Naur's "program theory" stays as attribution only.

Anchors (unchanged)

4mat · mental-model-according-to-naur · socratic-method · feynman-technique · blooms-taxonomy · definition-of-done

Notes

• Template uses plain paragraphs (no markdown bold) because the contracts page escapes template text — verified the rendered output has no literal **, preserves the → arrows, and produces clean paragraph breaks.
• Changelog updated (== 2026-06-08).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Lehrmethodik „Explaining and Teaching" grundlegend überarbeitet mit klarer, strukturierter Anleitung
  • Neue Sicherheitsmechanismen eingeführt: Overfiring-Bremse und explizites Opt-out für Lernende
  • Präzisierter Teaching-Loop mit expliziten Triggern, diagnosegetriebener Methode und 4MAT-Sequenzierung
  • Verstärkte Verifizierung von Verständnis durch strukturiertes Gatekeeping
  • Inhalte in Deutsch und Englisch aktualisiert

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 7df45ed0-9989-4b2e-9df5-3131fcc8aedb

📥 Commits

Reviewing files that changed from the base of the PR and between 1397409 and 8f7fc52.

📒 Files selected for processing (2)

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

---

Walkthrough

Der Contract "Explaining and Teaching" wird mit präzisiertem Teaching-Loop, explizitem Gatekeeping, Socratic-Methode, 4MAT-Struktur und Learner-Opt-out verfeinert. Updates dokumentieren die neue Struktur in beiden Sprachversionen und Changelog.

Changes

Contract Refinement: Explaining and Teaching

Layer / File(s)

Zusammenfassung

Contract Templates und Changelog Update website/public/data/contracts.json, docs/changelog.adoc

Die englische und deutsche Template des "Explaining and Teaching"-Contracts werden von einer Loop/Bullets-Struktur auf eine diagnostizierend gesteuerte Lehr-Anweisung umgestellt. Neue Fokusses: Definition of Done für Verständnis, Socratic-Methode vor dem Lehren, 4MAT-Sequenzierung (Why → What → How → What-If), aktive Verifikation statt passiver Bestätigung, explizites Gatekeeping, Skalierung nach Frage-Größe und Opt-out-Mechanismus („just tell me"). Der Changelog dokumentiert die Verfeinerung mit benanntem Trigger, präzisierter Schrittfolge inklusive Grounding und Gates sowie neuem Steuerungsmechanismus.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• LLM-Coding/Semantic-Anchors#573: Führt den ursprünglichen "Explaining and Teaching"-Contract-Eintrag in denselben Dateien ein.
• LLM-Coding/Semantic-Anchors#574: Passt denselben Contract-Eintrag in contracts.json mit alternatives Wording und Struktur an.

🚥 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: Verbesserung und Präzisierung des 'Explaining and Teaching'-Vertrags durch Klarstellung der Trigger, Restrukturierung der Schritte, Hinzufügen von Sicherheitsmechanismen und Verallgemeinerung der Formulierung.
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.}