refine: rework Explaining and Teaching into a question-driven dialogue#584
Merged
rdmueller merged 1 commit intoJun 8, 2026
Merged
Conversation
…ven dialogue
The previous version made 4MAT the headlined backbone ("teach in 4MAT
order — Why → What → How → What-If") and dropped "fill the gaps with
questions, not answers". In practice the model lectured instead of asking,
and recited the scaffold (naming the 4MAT questions, explaining the Naur
view) — the prompt leaked into the output.
Rework, distilled from the original teaching prompt it came from:
- Open by having the learner restate what they know; teach the gap.
- One small step per turn, then stop and wait — no stacked steps.
- Fill the gap with questions, not answers (restored engine).
- Quiz with multiple-choice whose answer is withheld until the learner
commits; advance only when they can apply it to a fresh case.
- Anchors stay named, but as attributions on behavioural verbs, never as
an enumerated procedure; explicit "don't announce the method" guard
stops the scaffold leaking into the output.
Anchors unchanged. EN + DE mirrored; contracts.txt regenerated.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
WalkthroughDer PR aktualisiert die Dokumentation und Vorlagen für den „Explaining and Teaching"-Vertrag einheitlich: Das Changelog, die Kontaktreferenz und die JSON-Daten werden überarbeitet, um einen dialoggesteuerten, iterativen Lehrfluss mit schrittweisen Fragen, Quiz-Verifizierung und Anwendungsgating zu definieren. ChangesDokumentation des Explaining-and-Teaching-Vertrags
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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.
Inline comments:
In `@website/public/data/contracts.json`:
- Line 191: The "template" field in contracts.json uses the British/other
variant "afterwards" but needs the US-English "afterward"; update the string
value for the "template" key to replace "afterwards" with "afterward" (this will
also propagate to website/public/contracts.txt which is generated from this
field) — locate the "template" property in contracts.json and change the word
inside the quoted string accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 3ad9642d-2c25-4e01-b992-892100c528ff
📒 Files selected for processing (3)
docs/changelog.adocwebsite/public/contracts.txtwebsite/public/data/contracts.json
| "anchors": ["4mat", "mental-model-according-to-naur", "socratic-method", "feynman-technique", "blooms-taxonomy", "definition-of-done"], | ||
| "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.", | ||
| "template": "When asked to explain or teach something (including \"why does X…\"), act as a teacher running a dialogue, not a lecture — your goal is that the learner can apply it afterwards, not that you delivered it.\n\nStart by having the learner restate what they already understand (Socratic Method), so you teach the gap, not the whole topic; adjust depth on request (ELI5 / ELI-intern). Keep a short running checklist of what they must grasp — the problem and why it exists, the solution with its design decisions and edge cases, and why it matters — a Definition of Done for understanding, worked one item at a time.\n\nTake one small step per turn: fill the gap with questions, not answers; ask, or explain the next smallest piece in a few sentences and then check it — then stop and wait. Never stack several steps in one turn. Lead with why something matters before its mechanics (4MAT), and keep drilling into the why beneath the why — the reasoning behind the design, not just what it does (Naur); cover what and how too.\n\nCheck by quizzing, never \"makes sense?\" — open or multiple-choice questions; for multiple choice, vary which option is correct and don't reveal the answer until the learner has committed. The sharpest check is having them explain it back in their own words (Feynman Technique) or apply it to a fresh case; use a concrete artifact (an example, code, a trace) when it helps. React to the actual answer: if they've got it, advance; if not, give a short targeted hint and re-ask. \"Understood\" means they can use it on a new case, not recite it (Bloom's Apply, not recall) — don't move on, and don't end, until they've shown that.\n\nDon't announce or walk through the method you're using — let it shape what you do, not what you say. Scale to the question: a small factual ask gets a one-line answer, and the learner can say \"just tell me\" anytime. If you're unsure of the topic, learn it before teaching.", |
Contributor
There was a problem hiding this comment.
US-Englisch-Variante vereinheitlichen (afterward statt afterwards).
Für konsistente US-Englisch-Texte sollte hier afterward verwendet werden. Da website/public/contracts.txt aus diesem Feld generiert wird, behebt die Änderung beide Stellen auf einmal.
🔧 Vorschlag
- "template": "When asked to explain or teach something (including \"why does X…\"), act as a teacher running a dialogue, not a lecture — your goal is that the learner can apply it afterwards, not that you delivered it.\n\nStart by having the learner restate what they already understand (Socratic Method), so you teach the gap, not the whole topic; adjust depth on request (ELI5 / ELI-intern). Keep a short running checklist of what they must grasp — the problem and why it exists, the solution with its design decisions and edge cases, and why it matters — a Definition of Done for understanding, worked one item at a time.\n\nTake one small step per turn: fill the gap with questions, not answers; ask, or explain the next smallest piece in a few sentences and then check it — then stop and wait. Never stack several steps in one turn. Lead with why something matters before its mechanics (4MAT), and keep drilling into the why beneath the why — the reasoning behind the design, not just what it does (Naur); cover what and how too.\n\nCheck by quizzing, never \"makes sense?\" — open or multiple-choice questions; for multiple choice, vary which option is correct and don't reveal the answer until the learner has committed. The sharpest check is having them explain it back in their own words (Feynman Technique) or apply it to a fresh case; use a concrete artifact (an example, code, a trace) when it helps. React to the actual answer: if they've got it, advance; if not, give a short targeted hint and re-ask. \"Understood\" means they can use it on a new case, not recite it (Bloom's Apply, not recall) — don't move on, and don't end, until they've shown that.\n\nDon't announce or walk through the method you're using — let it shape what you do, not what you say. Scale to the question: a small factual ask gets a one-line answer, and the learner can say \"just tell me\" anytime. If you're unsure of the topic, learn it before teaching.",
+ "template": "When asked to explain or teach something (including \"why does X…\"), act as a teacher running a dialogue, not a lecture — your goal is that the learner can apply it afterward, not that you delivered it.\n\nStart by having the learner restate what they already understand (Socratic Method), so you teach the gap, not the whole topic; adjust depth on request (ELI5 / ELI-intern). Keep a short running checklist of what they must grasp — the problem and why it exists, the solution with its design decisions and edge cases, and why it matters — a Definition of Done for understanding, worked one item at a time.\n\nTake one small step per turn: fill the gap with questions, not answers; ask, or explain the next smallest piece in a few sentences and then check it — then stop and wait. Never stack several steps in one turn. Lead with why something matters before its mechanics (4MAT), and keep drilling into the why beneath the why — the reasoning behind the design, not just what it does (Naur); cover what and how too.\n\nCheck by quizzing, never \"makes sense?\" — open or multiple-choice questions; for multiple choice, vary which option is correct and don't reveal the answer until the learner has committed. The sharpest check is having them explain it back in their own words (Feynman Technique) or apply it to a fresh case; use a concrete artifact (an example, code, a trace) when it helps. React to the actual answer: if they've got it, advance; if not, give a short targeted hint and re-ask. \"Understood\" means they can use it on a new case, not recite it (Bloom's Apply, not recall) — don't move on, and don't end, until they've shown that.\n\nDon't announce or walk through the method you're using — let it shape what you do, not what you say. Scale to the question: a small factual ask gets a one-line answer, and the learner can say \"just tell me\" anytime. If you're unsure of the topic, learn it before teaching.",🤖 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` at line 191, The "template" field in
contracts.json uses the British/other variant "afterwards" but needs the
US-English "afterward"; update the string value for the "template" key to
replace "afterwards" with "afterward" (this will also propagate to
website/public/contracts.txt which is generated from this field) — locate the
"template" property in contracts.json and change the word inside the quoted
string accordingly.
Source: Linters/SAST tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reworks the Explaining and Teaching contract so it actually behaves like the great teaching session it was distilled from — a Socratic back-and-forth — instead of a lecture.
Why
The previous version (#581) made 4MAT the headlined backbone ("teach in 4MAT order — Why → What → How → What-If") and, while tightening the Socratic wording, dropped "fill the gaps with questions, not answers". In practice the model lectured instead of asking, and recited the scaffold — naming the four 4MAT questions, explaining "the Naur view" — so the prompt leaked into the output. Testing showed it was also strongly model-dependent.
Root cause
A named anchor used as an attribution on a behavioural verb is a prior (good — it conditions). The same anchor turned into an enumerated procedure becomes a script the model recites (leaks). The regression was structural, not "too many anchors": the engine sentence was deleted and one anchor (4MAT) was promoted from a parenthetical to an enumeration.
What changed
Scope
contracts.jsonENtemplate+ DEtemplateDe(anchors array unchanged).contracts.txtregenerated;changelog.adocentry updated.**, 5 paragraphs EN/DE, all six anchors present by name (so in-text highlighting still works).llms.txt/all-anchors.adocleft untouched, as in feat(contracts): per-contract copy, header-free export, live language switch, contracts.txt #583.)🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes