Amateurfunk-Anki/EXPLANATIONS.md

# Explanations — agent-authored answer rationales

This document is the working contract for any AI agent (or human)
asked to **add or improve explanations** for questions in the BNetzA
amateur-radio catalog. The decks built by `amateurfunk_anki.py`
optionally append an English explanation block to the back of each
card; the text of those explanations lives in `explanations.json` at
the repo root and is edited by hand (or by an agent following this
file).

The build is non-blocking on this data: a missing file or missing
entry just produces a card without an explanation block. Adding an
entry is purely additive — no regenerate ceremony beyond
`make anki`.

---

## 1. File location and shape

- **Path:** `explanations.json` at the repo root. Tracked in git.
- **Encoding:** UTF-8, no BOM, two-space indent for readability.
- **Top level:** a JSON object keyed by **question number** exactly
  as it appears in the catalog (e.g. `"NA101"`, `"BA205"`,
  `"EH410"`). Keys are case-sensitive.
- **Sort order:** keep keys in alphabetical order. Diffs stay clean
  and merge conflicts get easier; the build does not care.

### Per-entry schema

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 |
| `source`      | string  | Non-empty. URL or citation like `AFuV §16(2)` |
| `confidence`  | integer | `1..10` inclusive. See scale in §5         |

Extra keys are rejected by `load_explanations()` — the build fails
with `unknown fields [...]` listing them. The loader is similarly
strict about types: a JSON `true` will not satisfy the integer
contract for `revision` or `confidence`. If you need to track
editorial metadata that isn't shown on the card, propose a schema
change rather than smuggling fields in.

Top-level keys (the question numbers) must also match the catalog
exactly. An entry keyed on a number that no live question carries
(typo, stale ID after a catalog revision) fails the build with
`explanation keys not present in the catalog: ...`. Fix the key, or
remove the entry.

### Minimal example

```json
{
  "NA101": {
    "revision": 1,
    "explanation": "100 m weighs 210 g, so 55 g is 55/210 of 100 m ≈ 26.2 m. Mass scales linearly with length for the same wire.",
    "source": "https://50ohm.de/lernen/wissen/elektrotechnik-mathematik",
    "confidence": 8
  }
}
```

The build appends this on the back card as a styled block headed
**Explanation**, with the source rendered as a clickable link when
it looks like an HTTP(S) URL.

---

## 2. How the explanation reaches the card

`amateurfunk_anki.py` does the wiring; the agent does not need to
modify Python code to ship a new explanation. End-to-end:

1. `load_explanations(./explanations.json)` parses the file and
   validates each entry against the schema above. A malformed entry
   is a hard build error.
2. While rendering a card, `render_question()` looks up the
   question's `number` in the dict. On a hit, `render_explanation()`
   produces an HTML block: header "Explanation", the body (with
   inline `$...$` LaTeX rewritten to MathJax `\(...\)`, same as the
   question text), and a "Source: ..." line.
3. The block lands inside `.af-back` at the very end, styled by the
   `.af-explanation*` CSS rules — serif italic body, sans-serif
   metadata, separated from the answer by a top border. When the
   entry's `confidence` is **below 7**, a small "low confidence"
   badge appears next to the **Explanation** header — a hint to the
   learner that the reasoning may be incomplete or weakly sourced.
   `revision` is never shown on the card.
4. The note GUID is keyed on `category.slug:number`, NOT on field
   content, so adding/changing an explanation does **not** create
   duplicate cards on re-import — Anki updates the existing note in
   place.

Run `make anki` (or `python3 amateurfunk_anki.py`) after editing the
file. The CLI summary line will show `... N with explanations` per
deck.

---

## 3. Locating a question to explain

Questions live in the JSON catalog under the per-edition data
directory:

```
data/<slug>/fragenkatalog<edition>.json
```

To find one by number, e.g. `EH410`:

```sh
python3 -c '
import json, glob
for path in glob.glob("data/*/fragenkatalog*.json"):
    cat = json.load(open(path))
    def walk(node, prefix=()):
        for q in node.get("questions", []) or []:
            if q["number"] == "EH410":
                print(json.dumps(q, ensure_ascii=False, indent=2))
                print(" / ".join(prefix))
        for s in node.get("sections", []) or []:
            walk(s, prefix + (s.get("title", "?"),))
    walk(cat)
'
```

You get the question stem, the four answers (`answer_a` is the
**correct** one upstream; the deck shuffles before display), the
class digit (`"1"` = N, `"2"` = E, `"3"` = A), and the section path.
That path tells you the topic context — useful when choosing a
source citation.

---

## 4. Writing the explanation

### Style

- **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.
- **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
  rule of thumb.
- **Math.** Use inline `$...$`; it's rewritten to MathJax on the
  card, same as for question text. Don't use display math `$$...$$`
  (the deck has no MathJax support for those).
- **Inline emphasis.** `<u>...</u>` is the only HTML you should
  type by hand. Everything else gets HTML-escaped.
- **No spoilers about other answers.** If a distractor is a common
  trap, naming the trap is fine; quoting the distractor's text is
  noise.

### What "WHY-focused" means in practice

| Less useful                                  | More useful                                   |
|----------------------------------------------|-----------------------------------------------|
| "The correct answer is 26.2 m."              | "55 g is 55/210 of 100 m by mass scaling."    |
| "Because regulations require it."            | "AFuV §16(2): only class A may operate ≤10 m." |
| "It's how the formula works."                | "Q is reactance over resistance, so Q rises as R falls." |

If the *only* honest explanation is "memorize the table" (e.g. a
band-plan lookup), say that plainly and cite the band plan in
`source` — confidence stays low (3–4) until someone finds a deeper
hook.

---

## 5. Confidence scale

| Score | Meaning                                                                |
|------:|------------------------------------------------------------------------|
| 10    | Direct quote / arithmetic restatement from a primary legal source.     |
|  8–9  | Derivation from a well-known formula or law text; no ambiguity.        |
|  6–7  | Reasoning sound but condensed; a reviewer might want one more line.    |
|  4–5  | Educated guess based on context; corroborating source is weak.         |
|  1–3  | Best-effort placeholder. Flag for re-explanation.                      |

When in doubt, score lower. The query "explain everything below
confidence 7" is a real workflow — a too-generous score hides work
that should be redone.

The score is also capped by the source tier — see §6 "Source ↔
confidence linkage". A tier-8 (general web) source caps confidence
at 5 regardless of how persuasive the prose is.

**Card surface.** Confidence below 7 also surfaces a "low
confidence" badge on the card itself (see §2). This is deliberate:
the learner sees that the explanation is provisional rather than
trusting it as definitive. Scoring 7 turns the badge off, so do
not nudge a 6 to a 7 just to clear the badge — fix the explanation
or the source first.

---

## 6. Sources

Use the **strictest tier that actually answers the question**. Drop
down a tier only when the higher one doesn't cover the topic — never
because a lower-tier source is easier to find. The exam tests
knowledge of German law and BNetzA-curated material; a primary-law
question backed by a random tutorial site is a worse explanation
than no explanation at all.

The full priority order, top (most preferred) to bottom:

1. **Primary German law.**
   - AFuG (Amateurfunkgesetz), AFuV (Amateurfunkverordnung), BEMFV,
     TKG when applicable, plus frequency-allocation ordinances
     (vfg / VVnömL).
   - Canonical URL pattern: `https://www.gesetze-im-internet.de/<gesetz>/__<§>.html`.
     Cite as `AFuV §16(2)` style. Use the URL form when possible so
     the card link is clickable.
   - If a question's answer is fixed by German law, **no lower tier
     is acceptable** as the sole source.

2. **EU / international regulation binding on Germany.**
   - CEPT recommendations (T/R 61-01, T/R 61-02), ITU Radio
     Regulations, ECC decisions, EU EMC / RED directives.
   - Use `docdb.cept.org/...` or the ITU document portal as the
     canonical URL.
   - Reach for this tier when the question references CEPT
     licensing, foreign operation, or harmonised band plans that
     AFuV doesn't restate.

3. **BNetzA official publications.**
   - The question catalog's own `README.txt`, BNetzA "Vfg"
     announcements, the German band plan as published by BNetzA,
     official explanatory notes.
   - Useful when primary law is too terse to convey the *why* on
     its own — these are the regulator's own gloss on the law.
   - Do not cite the question catalog PDF/ZIP itself as an
     explanation source. It proves what the official answer is, but
     it usually does not explain why that answer is right. Use a
     law, regulation, BNetzA notice, DARC/50ohm study page, standard,
     or other source that actually supports the explanation.

4. **German amateur-radio organisations.**
   - DARC publications and band plan (`darc.de`), Runder Tisch
     Amateurfunk (RTA) papers, **50ohm.de** (the community study
     site linked from `README.md`).
   - Exam-aligned by community convention; well-suited to the WHY
     when law text alone isn't pedagogically clear.

5. **International amateur-radio organisations.**
   - IARU Region 1 documents (Germany is in R1) and DARC's IARU R1
     liaison material; ARRL publications when they explain the
     underlying physics or an internationally harmonised band plan.
   - ARRL is **not** a source for German licensing rules — don't
     use it that way.

6. **Standards bodies and primary technical references.**
   - NIST, IEEE, IEC, ITU-R recommendations, ETSI standards (when
     not already binding via tier 2).
   - Appropriate for purely technical questions — units, defining
     equations, definitions — where no amateur-radio-specific
     source applies.

7. **Established engineering references.**
   - University lecture notes hosted by the university, recognised
     EE textbook publishers, well-known authors' personal sites.
   - Use only when tiers 1–6 don't cover the topic.

8. **General web technical sites — last resort.**
   - Wikipedia, tutorial sites (`allaboutcircuits.com`,
     `amateur-radio-wiki.net`, `biopac.com`, etc.), random
     manufacturer pages, blog posts.
   - **Treat citations at this tier as temporary.** Score
     `confidence` ≤ 5 and consider the entry a §8.3 candidate for
     re-sourcing the moment a higher-tier source is identified.
     Never use a tier-8 source as the sole citation for a question
     that has a clear answer in tiers 1–4.

### Source ↔ confidence linkage

The §5 confidence scale isn't independent of the tier:

- Tier 1–2 + sound derivation → 9–10 is appropriate.
- Tier 3–4 → cap at 8 unless the source quotes a primary citation.
- Tier 5–6 → cap at 7.
- Tier 7 → cap at 6.
- Tier 8 (sole source) → cap at 5. Flag for re-sourcing.

This isn't a hard limit the validator enforces — it's editorial
discipline. If you find yourself wanting confidence 9 with a
tier-7 source, you almost always either (a) need to find the
tier-1–4 source that backs the same claim, or (b) are about to
overstate certainty.

### Form

If the source is a URL, store it as one — `_source_html()` makes
plain `http://` / `https://` strings clickable. Mixed text+URL
sources are stored verbatim and rendered as escaped text (no auto
link), so prefer one or the other. A short citation like
`AFuV §16(2), gesetze-im-internet.de/afuv_2005/__16.html` is
acceptable but loses click-through. When possible, narrow the
source to a single canonical URL.

---

## 7. Revisions

`revision` is editorial bookkeeping; it never appears on the card.

- A brand-new entry starts at `revision: 1`.
- **Bump** when you materially improve the explanation, broaden the
  source, or fix an error. A typo fix is not a revision bump.
- Don't lower the revision. If a previous revision was wrong, fix
  it forward and explain the fix in the commit message.
- A revision bump usually pairs with a confidence bump (or, more
  rarely, with a deliberate confidence reset to indicate the
  reviewer is less sure than the prior author was).

---

## 8. Workflows

These are the common ways the file gets edited. The agent should
read the request and pick one.

### 8.1 "Explain question X"

1. Look up X in the catalog (§3) — read the stem, the correct
   answer (`answer_a` upstream), and the section path.
2. Identify *why* the correct answer is correct. Reach for a
   primary source before paraphrasing 50ohm.de.
3. Draft the body per §4, pick a source per §6, score honestly
   per §5.
4. Open `explanations.json`, insert the new entry in **alphabetical
   key order**, save.
5. Run `python3 -m unittest test_amateurfunk_anki` — the schema
   validator runs as part of the build path used by tests, so a
   typo'd entry fails fast.
6. Rebuild decks (`make anki`) and spot-check the new entry on
   the back of the card.

### 8.2 "Explain every question that doesn't have an entry yet"

This is bulk work — handle it in chunks, not as one giant batch.

1. Compute the unexplained set:

   ```sh
   python3 -c '
   import json, glob
   catalog = next(iter(glob.glob("data/*/fragenkatalog*.json")))
   exp = json.load(open("explanations.json"))
   def walk(n):
       for q in n.get("questions", []) or []: yield q["number"]
       for s in n.get("sections", []) or []: yield from walk(s)
   missing = sorted(set(walk(json.load(open(catalog)))) - exp.keys())
   print(len(missing), "questions unexplained")
   print("\n".join(missing[:20]))
   '
   ```

2. Process in groups of ~10 within one topic. Same section path
   often shares one source citation, so context stays warm and
   confidence scores stay consistent.
3. After each group, save and run the tests. Don't accumulate
   hundreds of unsaved entries.

### 8.3 "Improve all entries with confidence below N"

1. List low-confidence entries:

   ```sh
   python3 -c '
   import json
   exp = json.load(open("explanations.json"))
   for k, v in sorted(exp.items()):
       if v["confidence"] < 7: print(k, v["confidence"], "—", v["source"])
   '
   ```

2. For each, look up the question (§3), seek a stronger source
   (§6), rewrite if the new source changes the framing.
3. **Bump `revision`** and update `confidence` to reflect the new
   evidence. Do not just bump confidence without changing anything
   else — that's how bad explanations entrench themselves.

### 8.4 "This explanation is wrong"

1. Read the current entry. Confirm the error against the catalog
   stem and the cited source.
2. Rewrite the body, replace the source if needed, bump
   `revision`, and re-score `confidence` from scratch (don't carry
   over the prior score).
3. Commit message should name the question number and summarize
   what was wrong — future agents need to know what kind of
   mistake to look for elsewhere.

---

## 9. Validation checklist

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.
- [ ] `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
      the explanation.
- [ ] Keys remain in alphabetical order in the file.
- [ ] `python3 -m unittest test_amateurfunk_anki` passes.

---

## 10. What's out of scope here

- **Translating questions into English.** The cards are bilingual
  by design: German question + English explanation. Don't
  paraphrase the German.
- **Editing the catalog itself.** `data/` is a build artifact —
  refreshed by `amateurfunk_fetch.py` from BNetzA. Mistakes in the
  upstream questions are upstream's to fix.
- **Removing explanations.** If an entry is genuinely useless, fix
  it forward (§8.4). Don't delete keys — that loses the audit
  trail. (The schema doesn't currently encode "retracted", so if
  you ever need it, propose a schema change.)