refine: sharpen the Explaining and Teaching contract

docs/changelog.adoc

@@ -2,6 +2,12 @@
 
 A chronological record of all semantic anchors added to the catalog. Community contributors are credited with thanks.
 
+== 2026-06-08
+
+*Refined contracts:*
+
+* *Explaining and Teaching* — sharpened the teaching loop: names its trigger ("explain / why / how"), reorders to the actual flow (ground yourself → frame the checklist → diagnose → teach one item in 4MAT order → verify → gate), adds a grounding step (learn the current state before teaching, don't teach from stale memory), an over-fire brake (a one-line question gets a one-line answer) and an explicit learner opt-out; generalised away from code-only wording so it applies to any topic
+
 == 2026-06-03
 
 *New anchors:*

website/public/data/contracts.json

@@ -188,8 +188,8 @@
     "description": "How to teach a topic until understanding is verified, not just explained",
     "descriptionDe": "Wie man ein Thema lehrt, bis das Verständnis geprüft ist — nicht nur erklärt",
     "anchors": ["4mat", "mental-model-according-to-naur", "socratic-method", "feynman-technique", "blooms-taxonomy", "definition-of-done"],
-    "template": "Teach until the learner genuinely understands — don't just explain.\n\nSequence each unit Why → What → How → What-If (4MAT): motivation before detail. Treat the Why as Naur's program theory — the reasoning, trade-offs, and branches not taken behind the design, not merely what the code does; drill recursively into why.\n\nDiagnose first (Socratic Method): have the learner restate their current understanding, then fill the gaps with questions, not answers, adjusting depth on request (ELI5 / ELI-intern). The sharpest check is having them explain it back in plain words (Feynman Technique) — where they stall is the gap.\n\nKeep a running, written checklist of what must be grasped — high level (why it matters, what it impacts) and low level (logic, edge cases, design decisions) — a Definition of Done for understanding.\n\nThe loop:\n- After each point, verify by active recall — an open or multiple-choice question, a code walkthrough, the debugger — never \"makes sense?\".\n- \"Understood\" means Bloom's Apply/Analyze level (use it on a new case, trace the edge cases), not recall.\n- Don't advance until the current point is demonstrated, and don't end until the whole checklist is.\n\nScale the ceremony to the size of the question.",
-    "templateDe": "Lehren, bis die lernende Person es wirklich versteht — nicht nur erklären.\n\nJede Einheit in der Reihenfolge Why → What → How → What-If aufbauen (4MAT): Motivation vor Detail. Das Why als Naurs Programm-Theory behandeln — die Begründung, die Trade-offs und die nicht gewählten Alternativen hinter dem Design, nicht bloß was der Code tut; rekursiv ins Warum bohren.\n\nErst diagnostizieren (Socratic Method): die Person ihr aktuelles Verständnis zurückgeben lassen, dann die Lücken mit Fragen statt Antworten füllen und die Tiefe auf Wunsch anpassen (ELI5 / ELI-intern). Die schärfste Probe ist das Zurückerklären in einfachen Worten (Feynman Technique) — wo sie stockt, ist die Lücke.\n\nEine laufende, schriftliche Checkliste führen, was verstanden sein muss — high level (warum es zählt, was es beeinflusst) und low level (Logik, Edge Cases, Design-Entscheidungen) — eine Definition of Done fürs Verständnis.\n\nDie Schleife:\n- Nach jedem Punkt durch active recall prüfen — eine offene oder Multiple-Choice-Frage, ein Code-Walkthrough, der Debugger — nie \"passt das?\".\n- \"Verstanden\" heißt Blooms Apply/Analyze-Stufe (auf einen neuen Fall anwenden, Edge Cases durchspielen), nicht Abrufen.\n- Nicht weitergehen, bis der aktuelle Punkt demonstriert ist, und nicht enden, bis die ganze Checkliste es ist.\n\nDie Zeremonie an die Größe der Frage anpassen.",
+    "template": "When asked to explain or teach something (including \"why does X…\"), don't just deliver the answer — teach until the learner can use it, and gate on evidence they can.\n\nGround yourself first: if the topic is unfamiliar, fast-moving, or you're unsure, learn its current state before teaching — go to the source (the actual code, the spec, the docs), don't teach from stale memory.\n\nFrame: write a running checklist of what must be grasped — high level (why it matters, what it impacts) and low level (logic, edge cases, design decisions). That checklist is the Definition of Done for understanding.\n\nDiagnose before you teach (Socratic Method): start from the learner's current understanding, so you teach the gap, not the whole topic. Adjust depth on request (ELI5 / ELI-intern).\n\nTeach one item at a time in 4MAT order — Why → What → How → What-If: motivation before detail. Treat the Why as Naur's program theory — the reasoning, trade-offs, and branches not taken behind the design, not merely what it does; drill recursively into why.\n\nVerify — never \"makes sense?\". Check by active recall: have the learner explain it back in plain words (Feynman Technique — where they stall is the gap) or apply it to a new case (the What-If). \"Understood\" means Bloom's Apply/Analyze (uses it on a new case, traces the edge cases), not recall.\n\nGate: don't advance to the next item until the current one is demonstrated, and don't end until the whole checklist is.\n\nScale the ceremony to the question — a one-line factual question gets a one-line answer, not a loop. The learner can opt out any time (\"just tell me\") — comply.",
+    "templateDe": "Wenn du etwas erklären oder lehren sollst (auch „warum macht X…“), liefere nicht einfach die Antwort — lehre, bis die lernende Person es anwenden kann, und gate auf den Nachweis, dass sie es kann.\n\nErst dich selbst grounden: wenn das Thema unbekannt, schnelllebig oder du unsicher bist, lerne den aktuellen Stand, bevor du lehrst — geh an die Quelle (den tatsächlichen Code, die Spec, die Doku), lehre nicht aus veraltetem Gedächtnis.\n\nRahmen setzen: eine laufende Checkliste führen, was verstanden sein muss — high level (warum es zählt, was es beeinflusst) und low level (Logik, Edge Cases, Design-Entscheidungen). Diese Checkliste ist die Definition of Done fürs Verständnis.\n\nErst diagnostizieren, dann lehren (Socratic Method): beim aktuellen Verständnis der Person ansetzen, damit du die Lücke lehrst, nicht das ganze Thema. Die Tiefe auf Wunsch anpassen (ELI5 / ELI-intern).\n\nEinen Punkt nach dem anderen in 4MAT-Reihenfolge lehren — Why → What → How → What-If: Motivation vor Detail. Das Why als Naurs Programm-Theory behandeln — die Begründung, die Trade-offs und die nicht gewählten Alternativen hinter dem Design, nicht bloß was es tut; rekursiv ins Warum bohren.\n\nPrüfen — nie „passt das?“. Durch active recall: die Person es in einfachen Worten zurückerklären lassen (Feynman Technique — wo sie stockt, ist die Lücke) oder auf einen neuen Fall anwenden lassen (das What-If). „Verstanden“ heißt Blooms Apply/Analyze-Stufe (auf einen neuen Fall anwenden, Edge Cases durchspielen), nicht Abrufen.\n\nGate: nicht zum nächsten Punkt weitergehen, bis der aktuelle demonstriert ist, und nicht enden, bis die ganze Checkliste es ist.\n\nDie Zeremonie an die Größe der Frage anpassen — eine einzeilige Faktfrage bekommt eine einzeilige Antwort, keine Schleife. Die lernende Person darf jederzeit aussteigen („sag’s mir einfach“) — dem folgen.",
     "category": "communication"
   },
   {