diff --git a/docs/changelog.adoc b/docs/changelog.adoc index 34ec83b..cad5a3d 100644 --- a/docs/changelog.adoc +++ b/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:* diff --git a/website/public/data/contracts.json b/website/public/data/contracts.json index 2f52963..fae8b67 100644 --- a/website/public/data/contracts.json +++ b/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" }, {