knowledge-exam

Files (1)

• SKILL.md

SKILL.md (first lines)

# Knowledge Exam Skill

## Purpose

This skill creates a German knowledge-check exam for a specific class folder
based on the taught material (class Git history, cohort directories and the
WebUntis Lehrstoff record). Use it when asked to generate a mini-exam from the
material covered in class.

## Output Language: MANDATORY GERMAN

The generated exam and solution files MUST be written in natural German with 
proper UTF-8 umlauts (ä, ö, ü, ß). 
Never use English for the exam questions or solutions.

## Target Repository: the private `-T` exam repo (MANDATORY)

Knowledge-check exam and solution files must be written into the teacher's
**private test/exam repository** — the sibling repo named `<subject>-T`
(e.g. `GRG-PMM-T` for `GRG-PMM`), and **only there**. **Never write them into
the public teaching repo.** After the Quality Gate they are committed and
pushed in that private repo (protocol step 7).

Before generating files:

1. Locate the `-T` repo on disk (typically `~/repos/<owner>/<subject>-T`);
   if it does not exist, stop and ask the user.
2. Verify it is up to date (`git fetch && git status -sb`).
3. Read the target repo's `AGENTS.md` — it defines repo-specific conventions:
   file naming (`knowledge_<klasse>_<date>.md` + `_solutions.md`), class
   folder layout (flat vs. dated subfolder, cohort suffixes like `4ahwit-x`),
   and the formelle Anrede rule (Du vs. Sie per class).

Additional rules (discovered in practice):

- **Prüfungs-Angaben gehören IMMER ins `-T`-Repo** — Knowledge-Checks, PLFs
  und sonstige Prüfungsangaben, niemals ins öffentliche Teaching-Repo.
  HÜ-/Aufgaben-Dateien (`Aufgabe.md` im Klassenordner) sind *keine*
  Prüfungs-Angaben: sie bleiben im Teaching-Repo, damit Schüler:innen sie
  per Clone erreichen (homework-Workflow).
- **Fehlender Kohorten-Ordner im `-T`-Repo ist normal** bei Semesterstart
  (neues SJ: alte `4aaif/`-artige Ordner liegen noch flach im Root, die
  neuen `3aaif/` etc. existieren noch nicht). In diesem Fall den Ordner
  nach den `-T`-AGENTS.md-Konventionen anlegen — nicht abbrechen.
- **Der Zug ist im Klassennamen kodiert** (`3aaif` vs. `3caif`, bzw.
  `3ahwii`-artige Kürzel) — keine künstlichen Zusatz-Suffixe erfinden
  (`-x`, `-a` o. ä.), außer das `-T`-AGENTS.md verlangt sie explizit
  (z. B. bei mehreren parallelen Gruppen derselben Klasse).

## Inputs

- `class`: target class folder name.
- `fach`: (optional) WebUntis-Fachkürzel für den Lehrstoff-Abgleich, z. B.
  `WMC_1`. Wird es weggelassen, über `wu klasse <KLASSE> --details` auflösen
  (Suche nach dem eigenen Fach); schlägt das fehl, ohne WebUntis weiterarbeiten.
- `weeks`: (optional) Begrenzung der Git-Historie des Kohorten-Ordners als
  Zeitanker (Schritt 3); der Prüf-Umfang kommt primär aus WebUntis-Lehrstoff
  und Kohorten-READMEs.
- `exam-date`: (mandatory) the planned exam date, must be either:
  - An ISO date (YYYY-MM-DD format).
  - The literal `today`.
  - The literal `tomorrow`.
- `mc-count`: (optional) number of multiple-choice questions, default 10.
- `free-count`: (optional) number of free-text questions, default 3.

## Protocol

### 1. Validate Inputs

- **Mandatory exam-date parameter**: If `exam-date` is not provided, abort
  immediately with an error message explaining that this parameter is required.
- Confirm that a folder matching `class` exists in the **target `-T`
  repository** (see "Target Repository" section above), not in the teaching
  repo. If the folder does not exist, it may need to be created there —
  check the repo's AGENTS.md conventions first.
- If the `-T` repo cannot be located, stop and ask the user. If only the
  **class folder** is missing, that is normal at semester start — create it
  (see "Target Repository" above), do not abort.
- **Resolve exam-date to ISO format**:
  - If `exam-date` is an ISO date (YYYY-MM-DD), use it as-is.
  - If `exam-date` is `today`, compute today's ISO date.
  - If `exam-date` is `tomorrow`, compute tomorrow's ISO date.
  - Store this resolved date as `<isodate>` for output filenames.

### 2. Resolve Question Counts

- Default values: 10 multiple-choice questions, 3 free-text questions.
- If `mc-count` is not provided, set `mc-count = 10`.
- If `free-count` is not provided, set `free-count = 3`.
- If neither `mc-count` nor `free-count` was provided by the user:
  - Before generating, ask the user: "Sollen 10 MC-Fragen und 3 Freitext-Fragen generiert werden? (j/n)"
  - If the user confirms, proceed with defaults.
  - If the user declines, ask for specific counts before continuing.
- Do NOT ask for confirmation when at least one count was explicitly provided.

### 3. Stoffbasis: Kohorten-Dir, Lessons & WebUntis-Abgleich

Der Prüf-Umfang ist definiert durch **was tatsächlich unterrichtet wurde** —
nicht durch den Semesterplan. Drei Quellen, in dieser Reihenfolge gewichtet:

1. **WebUntis (Authoritäts-Quelle):** `wu lesson <KLASSE>/<FACH> termine
   --mit-lehrstoff` (z. B. `wu lesson 3AAIF/WMC_1 termine --mit-lehrstoff`)
   liefert alle Termine mit eingetragenem Lehrstoff. Achtung: bei langen
   Listen großzügigen Timeout setzen. Der Lehrstoff **fence**t den Prüf-Umfang:
   Fragen dürfen nichts abdecken, was dort nie aufgetaucht ist (z. B. Formulare
   in 3caif ja, in 3aaif nein — Stoffstand strikt kohorenscharf).
2. **Kohorten-Dir im Teaching-Repo:** datierte Tagesordner
   (`YYYY-MM-DD[_]thema/`) mit READMEs, Lesson-Dateien, Demos und
   Aufgabe-Dateien. Die READMEs spiegeln den realen Stoffstand inkl.
   Abgaben und Ausnahmen.
3. **Referenzierte Materialien:** Prepared Lessons (`unterricht/<PREFIX>-NN-*`),
   Beispielprojekte und Unterlagen, soweit sie von den Kohorten-READMEs
   verlinkt sind — dort steht die Stofftiefe für Detailfragen.

Ergänzend: Git-Historie des Kohorten-Ordners als Zeitanker
(`git log --since=<start> -- <kohorte>`), um den unterrichteten Zeitraum
abzugrenzen. Minimal-Commits sind Stunden-Anker, keine vollständige Abdeckung.

- Taucht bei erledigten Terminen **kein Lehrstoff** auf (Status „offen"),

From georgernstgraf/opencode-helpers, MIT.

More from georgernstgraf/opencode-helpers