repograde

Repograde Skill

Purpose

This skill is the canonical workflow for grading student Git repositories. It handles both full-history grading and date-filtered grading (commits from a specified cutoff date onwards) in a single unified workflow.

Output Language: MANDATORY GERMAN

Follow the grading-shared Output Language rule: natural German with proper UTF-8 umlauts (ä, ö, ü, ß), never English.

Dependencies

This skill relies on grading-shared for: Anrede-Gate (anrede.txt), email formulas, second-person address rules, database lookup, email JSON structure, name parsing from repository basename (CRITICAL: last word = first name, everything before it = last name), repository analysis protocol, assignment discovery protocol (Aufgaben-Discovery), bulk grading concurrency, German/UTF-8 constraints, JSON escaping rules, email body format, praise guidelines, Noten-TSV and reporting protocol.

Derive output filenames from the repository basename, while using the provided repository path verbatim to locate the repository.

Consistency Goal (CRITICAL)

The grading output of this skill MUST be highly standardized across repositories and across subagents. Do NOT improvise the structure, heading names, section order, or overall depth.

Every *_grading.md file generated by this skill MUST:

1. use the exact section order defined in REPORT-FORMAT.md,
2. include all mandatory numeric facts when evidence exists,
3. explicitly say when evidence is missing or unclear instead of silently omitting a section,
4. stay within the requested level of detail rather than expanding into a free-form essay.

Every *_email.json body generated by this skill MUST:

1. follow the exact paragraph order defined by grading-shared for assignment grading emails,
2. summarize the same core facts as the grading report,
3. keep a consistent scope and length across students.

Execution Context

This skill operates from a local folder (current working directory), NOT from within a Git repository. Calling this skill from inside a Git repository is an error.

The CWD contains student Git repositories as subdirectories. These may be structured as STUDENT_DIR/INNER_PROJECT/.git (two levels deep). The CWD may also contain name-based symlinks (e.g., Lastname Firstname -> STUDENT_ID) that provide the student's real name. A BROKEN name-symlink (target does not exist) means the student has not yet submitted their repository URL — see grading-shared Broken Name-Symlinks (Missing Repository).

Follow grading-shared Repository Structure Discovery (Inner Git Repository Discovery) before running any git commands. Use grading-shared Student Name Resolution via Symlinks to determine the student's name.

The CWD may also contain a _class symlink pointing to the corresponding class folder in the teaching repository (e.g., _class -> /home/georg/repos/GRG-SWP/2ahwii/). This symlink provides access to assignments and lesson materials.

Zielordner im -T-Repo (CRITICAL)

Alle Ausgaben dieses Skills werden im privaten -T-Repo abgelegt, niemals im Arbeitsverzeichnis mit den Schüler-Repos und niemals im öffentlichen Teaching-Repo.

Der normale Arbeitsplatz ist ~/gits/<kohorte>-<fach>/ (z. B. ~/gits/3aaif-wmc/): kein Git-Repo, darin die Namens-Symlinks auf die Schüler-Repos und der _class-Symlink ins öffentliche Klassen-Repo:

~/gits/3aaif-wmc/_class -> /home/georg/r/GRG-WMC/3aaif
~/gits/3aaif-wmc/Abazi Hamza -> Hamza473A

Auflösung (in dieser Reihenfolge):

1. CWD liegt bereits in einem -T-Repo: git rev-parse --show-toplevel liefert einen Pfad, dessen Basename auf -T endet → das ist die Wurzel.
2. Sonst über _class: readlink -f auf _class (immer auflösen — ~/r ist selbst ein Symlink auf repos/georgernstgraf/); das Ziel hat die Form /…/GRG-<FACH>/<kohorte> → -T-Wurzel ist das Schwesterverzeichnis /…/GRG-<FACH>-T, die Kohorte ist der Basename des Ziels.
3. Sonst: STOPP und den User fragen (kein Raten).

Zielordner: <T-Wurzel>/<kohorte>/<YYYY-MM-DD>_<slug>/ (z. B. ~/r/GRG-WMC-T/3aaif/2026-11-08_repokontrolle/)

• <YYYY-MM-DD> = heutiges Datum des Laufs.
• <slug> = kurzer Lauf-Bezeichner (z. B. repos, repokontrolle); aus dem User-Auftrag ableiten, sonst repograde.
• Ordner bei Bedarf anlegen (mkdir -p) — ein neuer Semester-/Lauf-Ordner ist der Normalfall, kein Fehler.

Vor dem ersten Schreibzugriff läuft ein Probelauf (read-only): der aufgelöste -T-Ordner, der Zielordner und die geplante Dateiliste werden angezeigt; es wird nichts angelegt und nichts geschrieben. Erst danach wird gearbeitet.

Die Schüler-Repos bleiben im CWD und werden nur gelesen. roster.tsv ist eine Zwischendatei und landet unter /tmp/opencode/ (nicht im Lauf-Ordner, nicht im Commit). Committet wird am Ende im -T-Repo (siehe Commit-Protokoll).

Input

Arguments are inferred from the user's request. Parse the user message to determine the mode:

User provides	Mode
Nothing (just "grade" or similar)	Bulk mode, all commits
Repository path only	Single-repo, all commits
Date only (ISO format YYYY-MM-DD)	Bulk mode, filtered commits
Date + repository path	Single-repo, filtered commits

Date Validation

If a date argument is detected, it MUST strictly follow ISO 8601:

YYYY-MM-DD

Valid: 2025-03-15, 2024-12-01 Invalid: 2025-3-15, 15-03-2025, 2025/03/15, 2025-03

If the date is invalid, STOP IMMEDIATELY with error: "Invalid date format: '[input]'. Expected ISO date format: YYYY-MM-DD (e.g., 2025-03-15)"

Date Filtering Logic

When a date is provided:

1. Parse the cutoff date as YYYY-MM-DDT00:00:00 (midnight at start of day).
2. Only inspect commits where commit_date >= cutoff_date.
3. Use git log --after="YYYY-MM-DD" to filter commits.
4. An assignment is RELEVANT if its date is on or after the cutoff, or if it spans a period that includes the cutoff.

Plan Presentation (MANDATORY)

Before starting any grading work, present a plan to the user. The plan MUST include:

1. Mode: Single-repo or Bulk mode.
2. Date filter: If applicable, show the cutoff date; otherwise "All commits".
3. Assignments discovered: List all assignments found (date, topic, source location). This requires running the full grading-shared Assignment Discovery Protocol first.
4. Repositories to grade:
   • Single-repo: show the path and basename (or resolved symlink name if available).
   • Bulk: list all discovered student repositories (resolved student name from symlink where available, otherwise basename), with count.
5. Zielordner im -T-Repo: the resolved -T root, the run folder <kohorte>/<YYYY-MM-DD>_<slug>/ and whether it already exists (Probelauf, read-only — see Zielordner section).
6. Anrede: the word read from <kohorte>/anrede.txt (Du/Sie); missing file stops the run.
7. Output files that will be generated (inside the run folder):
   • Single-repo: <basename>_grading.md, <basename>_email.json, <basename>_points.json.
   • Bulk: per-repo files + GRADINGS.md + shared EMAIL.json + noten.tsv.
   • Date-filtered bulk also: CLASS.md.

Display this plan and proceed immediately without waiting for confirmation.

Modes

1. Single-repo mode

Use this mode when a repository path is provided (with or without a date).

Protocol:

1. Treat the repository path as provided verbatim.
2. Navigate to the student repository.
3. Follow the grading-shared Pre-Grading Verification.
4. Derive the output stem from basename of the repository path.
5. Discover assignments using the grading-shared Assignment Discovery Protocol and build a unified assignment list. If no assignment is found, stop immediately. (Assignment files are NEVER inside the student repository.)
6. If a date filter is active, filter commits to only those at or after the cutoff date.
7. Follow the grading-shared Repository Analysis Protocol to inspect the repository history and actual commit content, not just commit messages.
8. Evaluate work against the assignment periods and produce an updated grading result in German.
9. Do not write INDIVIDUAL.md.
10. Do not write CLASS.md.
11. Do not modify shared EMAIL.json.
12. Generate <basename>_grading.md as the repository grading report in German (inside the -T run folder).
13. Generate <basename>_email.json as a JSON array with exactly one object, following grading-shared Email JSON Structure and Email Body Format, using German body text.
14. Generate <basename>_points.json as the points sidecar (see grading-shared Noten-TSV) — one object with name, kind: "homework", klasse and assignments[{from, to, label, max, points}].

2. Bulk mode

Use this mode when no repository path is provided (with or without a date).

Protocol:

1. Discover student repositories following grading-shared Repository Structure Discovery, Student Name Resolution via Symlinks, and Bulk Grading Protocol directory exclusion rules. Each student repo's git working directory may be one level deeper than the student directory. Broken name-symlinks are NOT an error and NOT skipped: they mark students without a submitted repository URL and are graded as no-repository cases (see No-Repository Students below).
2. Follow the grading-shared Bulk Grading Protocol for concurrency (default max 5, ~3 second delay between runs).
3. Each subagent writes only <basename>_grading.md, <basename>_email.json and <basename>_points.json in German, following grading-shared Email JSON Structure, JSON Escaping Rules, and Email Body Format, and the points-sidecar schema of the Noten-TSV section. Subagents MUST use the exact *_grading.md section headings and order defined in REPORT-FORMAT.md. They MUST NOT produce free-form reports with different lengths or different structures per student.
4. Subagents must never write shared EMAIL.json and never write noten.tsv.
5. Continue until all repositories are processed.
6. After all subagents finish:
   • Generate GRADINGS.md in German with class-wide overview table.
   • If a date filter is active, also generate CLASS.md in German.
   • Aggregate per-repo *_email.json files into shared EMAIL.json following grading-shared rules, including JSON Escaping Rules.
   • Build noten.tsv (see below).
7. Commit and push the run folder in the -T repo (see Commit-Protokoll).

2b. Noten-TSV und Commit (nach der Aggregation)

1. Roster beschaffen: wu lesson <KLASSE/FACH> roster > /tmp/opencode/roster.tsv (Fach aus der _class-Adresse, z. B. _class -> GRG-WMC/3aaif → wu lesson 3aaif/wmc roster). Schlägt wu fehl: STOPP mit deutscher Meldung.

2. Probelauf (read-only, Pflicht):

   ~/.opencode/skills/grading-shared/emit-grade-tsv.py --roster /tmp/opencode/roster.tsv
   

   Die Tabelle dem User zeigen.

3. Erst danach schreiben: … emit-grade-tsv.py --roster /tmp/opencode/roster.tsv --write (ergibt noten.tsv im Lauf-Ordner).

4. roster.tsv ist nur ein Zwischenprodukt und wird nicht committet.

5. Commit-Protokoll: im -T-Repo alle Ausgaben des Lauf-Ordners committen und pushen — deutsche Commit-Message nach der Repo-Konvention mit Issue-Nummer, z. B. Abgaben 3AAIF 2026-11-01: Bewertungen, E-Mails und Noten-TSV (#12). Ist keine Issue-Nummer bekannt, beim User nachfragen statt raten. Niemals im öffentlichen Teaching-Repo committen.

3. No-Repository Students (Broken Name-Symlinks)

A broken name-symlink in the CWD marks a student who has not yet submitted their repository URL. Per grading-shared Broken Name-Symlinks (Missing Repository):

1. Treat the student as a normal grading case (never stop, never skip).
2. Grade without evidence: ALL Abgaben 0%, Endbewertung: 0/100.
3. Generate <name>_grading.md (mandatory structure, every section explicitly stating "kein Repository — keine Evidence"), a <name>_email.json whose body follows the Missing Repository Emphasis variant (the URL submission is REQUIRED for a positive assessment), and a <name>_points.json with 0 points for every Abgabe.
4. Include the student in GRADINGS.md (0/100) and in the shared EMAIL.json.
5. Skip all git commands and the Pre-Grading Verification for these students.

Assignment Matching

After repository analysis, map the detected work onto the unified assignment list.

Step-by-Step Matching Process

1. Parse ALL assignment entries from the unified list.

2. Match commits to assignments:

   • For each commit, determine which assignment it relates to.
   • Use commit date + content to identify the relevant assignment period.
   • A commit dated 2026-02-20 likely belongs to an assignment dated 2026-02-18.

3. Build completion status for ALL assignments:

   • List all assignments in the unified list.
   • Mark each as completed or missing.

Matching with Date Filter

When a cutoff date is active:

Cutoff Date	Assignment Date	Match?	Reason
2026-02-10	2026-02-18	YES	Assignment given after cutoff
2026-02-10	2026-02-05	NO	Assignment before cutoff period
2026-02-10	2026-02-10	YES	Exact match
2026-02-10	2026-03-01	YES	Assignment within grading period

Important Considerations

• Parse ALL entries before matching — never stop at the first entry.
• Convert all dates to ISO format — use the same format for comparison.
• Include assignments from the cutoff date onwards — not just commits.
• Clearly indicate in the report whether grading covers all commits or from a specific date onwards.
• Base judgments on actual code and text changes, not only on commit messages.

Bewertung pro Abgabe (CRITICAL)

Jede Abgabe zählt 100 Basispunkte. Bei N Abgaben sind maximal N × 100 Prozentpunkte erreichbar. Die Endbewertung in /100 ergibt sich aus erreichte_Punkte / max_Punkte × 100.

Zwei Werte pro Abgabe

Für jede Abgabe werden zwei Werte ermittelt:

1. Quality (0–100%): Inhaltliche Bewertung — Korrektheit, Struktur, Vollständigkeit, technisches Verständnis. 0% wenn keine Abgabe erkennbar.
2. Factor (Pünktlichkeit): 1.0 (pünktlich) oder 0.75 (verspätet), gemäß grading-shared Deadline Calculation.

effective_score = Quality × Factor

Scoring Table (MANDATORY in every report and every email)

Jeder *_grading.md-Report und jede *_email.json MUSS exakt diese Scoring-Tabelle enthalten.

Format in *_grading.md (Markdown-Tabelle):

| Abgabe | Thema | Quality | Factor | Effective |
|--------|-------|---------|--------|-----------|
| 1      | [Thema] | 80% | 1.0 | 80% |
| 2       | [Thema] | 70% | 0.75 | 52.5% |
| 3       | [Thema] | —  | —  | 0% |

Format in *_email.json body (ASCII):

Abgabe 1 [Thema]: 80% (pünktlich) -> 80 Punkte
Abgabe 2 [Thema]: 70% (verspätet, daher 25% Abzug) -> 52.5 Punkte
Abgabe 3 [Thema]: nicht abgegeben -> 0 Punkte

Gesamtbewertung

erreichte_Punkte = sum(effective_score_i)
max_Punkte = Anzahl_Abgaben × 100
Endbewertung = round(erreichte_Punkte / max_Punkte × 100)

Beispiel: Fünf Abgaben, max. 500 Punkte:

Abgabe	Thema	Quality	Factor	Effective
1	Hono REST-API	80%	1.0	80%
2	Fetch Response	70%	0.75	52.5%
3	Promises	90%	1.0	90%
4	Transpile	—	—	0%
5	KI-Provider	60%	1.0	60%

Erreichte Punkte: 80 + 52.5 + 90 + 0 + 60 = 282.5 / 500 Endbewertung: 57/100 (57%)

Abdeckungsquote (informativ)

Abdeckungsquote = (Anzahl Abgaben mit Quality > 0%) / Anzahl_Abgaben × 100

Nicht abgegeben = 0%, abgegeben (auch verspätet) zählt für die Quote. Die Abdeckungsquote ist rein informativ; sie geht NICHT zusätzlich in die Endbewertung ein (fehlende Abgaben sind bereits mit 0% eingerechnet).

Edge Cases

• No assignments in period: Report clearly, grade based on available work only.
• Empty repository: Alle Abgaben 0% → Endbewertung 0/100.
• Broken name-symlink (kein Repository): alle Abgaben 0% → Endbewertung 0/100; E-Mail mit Missing Repository Emphasis (Pflicht) — siehe grading-shared Broken Name-Symlinks.
• Late submissions: Automatic 0.75 factor applied REGARDLESS of how late the submission is (no graduated penalty); noted explicitly in every relevant row of the scoring table.
• Deadline: gemäß grading-shared Deadline Calculation — nächste UE nach dem Aufgabendatum (via wu) bzw. eine explizite Deadline im Aufgabetext.

Outputs

All outputs are written into the -T run folder <T-Wurzel>/<kohorte>/<YYYY-MM-DD>_<slug>/ (see Zielordner section).

Single-repo mode

• <basename>_grading.md in German.
• <basename>_email.json as a one-entry JSON array following grading-shared rules and Email Body Format, with German body text.
• <basename>_points.json as the points sidecar.

Bulk mode (all commits)

• Per-repository <basename>_grading.md files in German.
• Per-repository <basename>_email.json files following grading-shared rules and Email Body Format, with German body text.
• Per-repository <basename>_points.json points sidecars.
• GRADINGS.md with class-wide overview table in German.
• noten.tsv as the Google-Doc import table (probelauf first, then written).
• Shared EMAIL.json, created only after all per-repo outputs are finished.

Bulk mode (date-filtered)

• Per-repository <basename>_grading.md files in German.
• Per-repository <basename>_email.json files following grading-shared rules and Email Body Format, with German body text.
• Per-repository <basename>_points.json points sidecars.
• GRADINGS.md with class-wide overview table in German (includes cutoff date in header).
• CLASS.md with anonymized class-wide patterns and teacher recommendations in German.
• noten.tsv as the Google-Doc import table.
• Shared EMAIL.json, created only after all per-repo outputs are finished.

GRADINGS.md Generation (Bulk Mode Only)

After all per-repository grading is complete in bulk mode, generate GRADINGS.md as a class-wide overview table.

Content Requirements

GRADINGS.md MUST include:

1. A table with columns for student identifier (repository basename or name) and final score (Endbewertung).
2. Ordered alphabetically by student name, NOT by grade.
3. Written in German.
4. If date-filtered, include the cutoff date in the header.

Example Structure

# Bewertungen

| Name | Endbewertung |
|------|-------------|
| Huber Maria | 85/100 |
| Maier Thomas | 72/100 |
| Schmidt Anna | 91/100 |

CLASS.md Generation (Date-Filtered Bulk Mode Only)

When a date filter is active in bulk mode, also generate CLASS.md as an anonymized class summary for the teacher.

Content Requirements

CLASS.md MUST include:

1. Overview: Summary of the grading period (cutoff date, number of repositories graded).
2. Common Patterns: Frequently observed strengths across submissions.
3. Common Weaknesses: Recurring issues or mistakes.
4. Assignment Completion Statistics: Aggregate completion ratios.
5. Teacher Recommendations: Actionable suggestions for addressing issues.

Anonymity Rules

• NEVER include student names or repository names that identify individuals.
• Use generic terms in German: "einige Schüler", "viele Abgaben", "vereinzelt".
• Focus on patterns, not individuals.
• This file may be committed to a public repository.

Reporting Expectations

The mandatory *_grading.md structure, its section-content requirements, and the subagent standardization rules are in REPORT-FORMAT.md.

Email Body

Every <basename>_email.json body MUST follow the grading-shared Email Body Format section exactly: plain ASCII text with code blocks as the only allowed Markdown, structured per the assignment grading email template, with subtle praise per the Praise Guidelines. All text MUST be in German.

Additionally, every repograde email body MUST summarize the following in the same fixed structure for every student:

1. greeting,
2. automatic assessment disclaimer paragraph,
3. grading period opening,
4. commit activity summary,
5. Abgaben-Übersicht (Abgabe 1: …, Abgabe 2: …),
6. Bewertungs-Absätze pro Abgabe — each ending with Bewertung: XX% and, if late, (verspätet, daher 25% Abzug auf den erreichten Wert),
7. scoring table (ASCII format per Bewertung pro Abgabe),
8. Erreichte Punkte and Endbewertung summary,
9. closing.

Within that fixed order, ensure that the combined Abgaben-Bewertung and scoring paragraphs clearly communicate code quality, missing work, lateness, and the final result. The Quality%, Factor, and Effective score of every Abgabe MUST all be visible per the Scoring Table format.

Do not vary this structure between students. For students WITHOUT a repository (broken name-symlink), the Missing Repository Emphasis variant replaces paragraph groups 3–6 (see grading-shared Email Body Format).

Constraints

• The grading work directory (typically ~/gits/<kohorte>-<fach>/) must NOT itself be inside a Git repository. All outputs go to the -T repo instead.
• This skill must NOT clone student repositories; use git pull to update.
• If uncommitted changes exist in any student repository, STOP IMMEDIATELY.
• If a date is provided and invalid, STOP IMMEDIATELY.
• Never commit student repositories or modify their history. The -T repo IS committed (see Commit-Protokoll) — that is the only commit this skill makes.
• All grading content follows grading-shared rules (German, second-person, UTF-8 umlauts, email structure, email body format, missing email handling).
• In single-repo mode, stop if no assignment source is found.
• In single-repo mode, a provided repository path that is a broken symlink is graded as a no-repository case (see No-Repository Students), not an error.
• In single-repo mode, never write INDIVIDUAL.md, CLASS.md, or shared EMAIL.json.
• In bulk mode, generate GRADINGS.md after all per-repo grading is complete.
• In date-filtered bulk mode, also generate CLASS.md.
• In bulk mode, generate shared EMAIL.json only after all per-repo outputs are complete.
• Run emit-grade-tsv.py in dry-run mode first and show the table; write noten.tsv only with --write.
• Stop immediately when <kohorte>/anrede.txt is missing or invalid (grading-shared Anrede-Gate).
• Use proper quoting for paths with spaces.
• Present the plan to the user BEFORE starting any grading work.
• Use pure AI evaluation for all grading; never write grading scripts. The sub-agent fan-out in bulk mode handles parallelism — do not write batch processing scripts or evaluation programs.

Done when

• [ ] Plan presented before any grading work: mode, date filter, assignments, repositories, -T run folder (read-only Probelauf) and the Anrede source.
• [ ] anrede.txt read via read-anrede.sh; a missing or invalid file stopped the run before the first write.
• [ ] Scoring table with Quality, Factor and Effective per Abgabe present in every *_grading.md and every email body.
• [ ] Single-repo mode: <basename>_grading.md, <basename>_email.json and <basename>_points.json written in the -T run folder.
• [ ] Bulk mode: per-repo files plus GRADINGS.md, shared EMAIL.json and noten.tsv (dry-run table shown first, --write only after) generated once the last subagent finished.
• [ ] Date-filtered bulk mode additionally produced CLASS.md without student names.
• [ ] No-repository students (broken name-symlinks) graded 0/100 with the Missing Repository Emphasis email, not skipped.
• [ ] Student repositories read-only: no commit, no history change, no clone; only the run folder committed and pushed in the -T repo.