Improve "Kenntnisse von Vorschriften" explanations

2026-06-04 11:59:48 +02:00
parent fdc5932d7d
commit 3ce060947d
3 changed files with 207 additions and 201 deletions
@@ -32,7 +32,7 @@ Every entry MUST have exactly these four fields:
 | Field         | Type    | Constraint                                 |
 |---------------|---------|--------------------------------------------|
 | `revision`    | integer | `>= 1`. Starts at `1`, bumps on improvement |
-| `explanation` | string  | Non-empty. **English.** Terse. WHY-focused |
+| `explanation` | string  | Non-empty. **English.** Correct & helpful, WHY-focused |
 | `source`      | string  | Non-empty. URL or citation like `AFuV §16(2)` |
 | `confidence`  | integer | `1..10` inclusive. See scale in §5         |

@@ -141,10 +141,15 @@ source citation.
 - **Language: English.** The questions and answers stay in German
  on the card; the explanation is the one English element. Don't
  switch.
- **Terse.** Aim for 1–3 sentences. The card already shows the
-  question, the correct answer text, and the breadcrumb — the
-  explanation should add the missing *why*, not restate any of
-  those.
+- **Correct and helpful first; length follows the topic.** There is
+  no sentence cap. Use as much room as the question genuinely needs —
+  a one-line arithmetic restatement for a simple lookup, a full
+  worked derivation or a multi-step rule walkthrough where that is
+  what makes the answer *click*. Don't pad: every sentence should
+  earn its place by adding correctness, context, or a usable hook.
+  The card already shows the question, the correct answer text, and
+  the breadcrumb — the explanation adds the missing *why* and the
+  understanding needed to get there, not a restatement of those.
 - **Lead with the reasoning.** Don't open with "The correct answer
  is X because..." — the card already declares the correct answer
  one line above. Go straight to the principle, the formula, the
@@ -406,7 +411,8 @@ Before saving, confirm:

 - [ ] Key is the exact catalog `number` (case-sensitive).
 - [ ] All four fields present, correct types, in range.
- [ ] `explanation` is English, terse, WHY-focused.
+- [ ] `explanation` is English, correct, helpful, WHY-focused — as
+      long as the topic needs, no longer.
 - [ ] `source` is non-empty and as primary as possible.
 - [ ] `revision` is correct (1 for new, bumped for improvement).
 - [ ] `confidence` honestly reflects how well the source supports