Templates

Copy-Paste-Skelette für die wichtigsten Doku-Artefakte. Zweck: Konsistenz beim Anlegen + niemand vergisst die wichtigen Felder.

Spec-Skeleton (P0-Freeze)

Pfad: prilog_docs/umsetzung/<thema>/prilog_<thema>_p0_freeze.md

# <Thema> — P0 Freeze v1

## 0. Was hat sich gegenüber Vorgänger-Version geändert?
(Nur ab v2 relevant — was wurde hinzugefügt/geändert/entfernt)

## 1. P0-Ziel
Ein Satz. „Nach diesem Sprint kann <Rolle> <Aktion>."

## 2. Explizit ausgeschlossen aus P0
- Punkt 1 (warum: …)
- Punkt 2 (warum: …)

## 3. Bestehende Entitäten wiederverwenden
- Person, Space, Subject, … — was nutzen wir aus existierenden Domänen

## 4. Rollenmodell + Capability-Flags
| Rolle | Was sie darf | Capability-Flag |
|---|---|---|
| <Rolle 1> | … | canDoX |

## 5. Datenmodell
- Tabelle X: Felder + FKs + Indices
- Tabelle Y: …
- ASCII-Diagramm oder Mermaid

## 6. Workflow-State-Machine
- States, Übergänge, Wer darf welchen Übergang
- Tabelle oder Mermaid-Diagramm

## 7. Sicht-Resolver (Datenschutz)
Pro Resource: wer darf lesen/schreiben?

## 8. DSGVO-Schichten
- Datenkategorien
- Rechtsgrundlage
- Pseudonymisierung
- Break-Glass-Pfad
- Retention
- Audit-Events

## 9. Endpoints
| Methode | Pfad | Capability | Beschreibung |

## 10. UI / Klick-Pfad
ASCII-Mockup oder Wireframe der drei wichtigsten Pfade

## 11. Edge-Cases + Fehler-Handling
- Was wenn Stundenplan-Bridge nichts findet?
- Was wenn 0 Bausteine?
- Was wenn JWT abgelaufen?

## 12. Risiken
| Risiko | Wahrscheinlichkeit | Schweregrad | Maßnahme |

## 13. Akzeptanzkriterien (= Definition of Done für diesen Sprint)
- [ ] Lehrer kann …
- [ ] Klassenleitung kann …
- [ ] Schulleitung kann …

## 14. Sprache + Konvention
Deutsch / Englisch / Tenant-spezifisch?

## 15. Spec-Eigentümer + Review-Zustand
- Owner: …
- Reviewer: …
- Status: ENTWURF | REVIEW | FREIGEGEBEN

PR-Template

Pfad: .github/pull_request_template.md (pro Repo)

## Was

Kurz: was ändert sich? (1-2 Sätze)

## Warum

Was ist der Schmerz oder die Anforderung? Referenz auf Spec/Issue.

## Wie getestet

- [ ] TSC clean
- [ ] Unit-Tests grün
- [ ] Per Hand durchgeklickt (welche Rolle, welcher Klick-Pfad)
- [ ] Real-DB-Probe (welcher Endpoint, gegen welchen Tenant)
- [ ] Mind. ein Edge-Case probiert (welcher)

## Schema-Migration?

- [ ] Nein
- [ ] Ja: Migration `0NNN_<name>` enthalten, Backfill berücksichtigt, auf
      Schatten-DB durchgespielt

## Rollback-Plan

Wenn das Deployment schief geht, was ist der Rollback?
(z. B. „revert commit + redeploy + Migration X manuell zurückrollen")

## DSGVO-relevant?

- [ ] Nein
- [ ] Ja: ComplianceGate aktualisiert, neue DSFA-Anlage, Sicht-Resolver,
      Audit-Events

## Breaking Changes

Wenn vorhanden, welche Konsumenten betroffen, welche Migrations-Doku
für die.

## Screenshots (bei UI-Änderungen)

Vorher / Nachher.

ADR (Architecture Decision Record)

Pfad: prilog_docs/adr/NNNN-<title-slug>.md

Format-Vorlage:

# NNNN — <Kurz-Titel>

- **Status:** ENTWURF | AKZEPTIERT | ABGELEHNT | ÜBERHOLT (durch NNNN)
- **Datum:** YYYY-MM-DD
- **Owner:** Name
- **Beteiligte:** Namen

## Kontext

Was ist die Situation? Welche Beobachtungen führten zu der Frage?

## Optionen

### Option A — <Bezeichnung>
- Vorteile
- Nachteile

### Option B — <Bezeichnung>
- Vorteile
- Nachteile

(Auch „Nichts tun" als Option diskutieren!)

## Entscheidung

Welche Option wird gewählt? Mit Begründung.

## Konsequenzen

Positive Folgen, negative Folgen, Was wird dadurch schwerer/leichter.

## Folge-Aktionen

- [ ] Migration starten
- [ ] Doku aktualisieren
- [ ] …

Postmortem

Pfad: prilog_docs/postmortems/YYYY-MM-DD-<incident-slug>.md

# Postmortem: <Incident-Titel>

- **Datum:** YYYY-MM-DD HH:MM
- **Dauer:** N Minuten / Stunden
- **Schweregrad:** SEV1 (komplett down) | SEV2 (Hauptfeature down) | SEV3 (Teilfunktion)
- **Betroffene:** N Tenants, geschätzt N Users
- **Owner Postmortem:** Name

## Zusammenfassung (TL;DR)

3-5 Sätze: was geschah, wie wurde es bemerkt, wie behoben, was lernen wir.

## Timeline

| Zeit | Ereignis |
|---|---|
| HH:MM | Erste Beobachtung |
| HH:MM | Detection (wer / wodurch) |
| HH:MM | Diagnose-Beginn |
| HH:MM | Mitigation deployed |
| HH:MM | Wiederherstellung verifiziert |

## Detection

Wie haben wir es bemerkt? (User-Report? Alert? Zufall?)
War das schnell genug?

## Diagnose

Welche Hypothesen wurden verfolgt? Was war Sackgasse? Was hat geholfen?

## Root Cause

Die echte Ursache (nicht die erste Vermutung).
Mehrere mögliche Layer: Code-Bug, Config, Infrastruktur, menschliche Aktion.

## Was hat geholfen

- Logs, die Aufschluss gaben
- Tools, die schnell halfen
- Personen, die schnell verfügbar waren

## Was hat gefehlt

- Welche Logs hätte ich gerne gehabt?
- Welche Monitoring-Alerts hätten früher angeschlagen?
- Welche Dokumentation hätte mir Zeit gespart?

## Action Items

| Was | Wer | Bis wann | Status |
|---|---|---|---|
| Z. B. Alert für DB-Disk hinzufügen | … | YYYY-MM-DD | offen |

## Lessons

Welche Regel kommt in `02-lessons-aus-prilog.md` (mit neuer L-NNN-ID)?

Sprint-Recap

Pfad: prilog_docs/umsetzung/<thema>/NN-sprintN-<bezeichnung>-live.md

# Sprint N — <Titel> LIVE

**Datum:** YYYY-MM-DD
**Spec:** `prilog_<thema>_p0_freeze_vN.md`
**Vorgänger:** [Sprint N-1](NN-sprint(N-1)-...-live.md)

## 1. Was kam dazu?

### 1.1 <Feature 1> (Task M)
- Service: `path/to/service.ts`
- Router: `path/to/router.ts`
- Frontend: `path/to/component.tsx`
- Wichtige Punkte: …

### 1.2 <Feature 2>
…

## 2. Tests

- N neue Tests, M Tests gesamt
- TSC backend/web clean

## 3. Migration

- `0NNN_<name>`: was sie tut, Backfill, Risiko

## 4. Deploy

- Backend commit `<sha>`
- Web-Client build `<sha>`
- Migrations live auf api.prilog.chat
- Reconcile auf alle Tenants gelaufen

## 5. Was bleibt offen

Was wurde BEWUSST nicht in diesem Sprint gemacht — als Backlog.

## 6. Hand-Test-Beweis

Wer hat als welche Rolle durchgeklickt? Welcher Tenant? Was funktionierte,
was nicht?

## 7. Real-DB-Probe

Output von `npx tsx scripts/...` — beweist, dass die Voraussetzungen
in der Live-DB existieren.

Bug-Issue-Template

Pfad: .github/ISSUE_TEMPLATE/bug.md

---
name: Bug-Meldung
about: Software-Fehler beschreiben
title: '[BUG] '
labels: bug
---

## Was passiert

Was beobachte ich konkret (Symptom, nicht Vermutung)?

## Was erwarte ich

Was hätte stattdessen passieren sollen?

## Reproduktion

1. ...
2. ...
3. ...

## Umgebung

- Welcher Tenant?
- Welche Rolle (Login-Name)?
- Browser + Version?
- Mobile / Desktop?

## Screenshots

(bitte einfügen wenn möglich)

## Häufigkeit / Auswirkung

- Tritt das immer auf? Manchmal?
- Wie viele User betroffen?
- Blockiert es Arbeit?

## Eigene Vermutung

(optional — was glaubst du, woher es kommt?)

Feature-Request-Template

Pfad: .github/ISSUE_TEMPLATE/feature.md

---
name: Feature-Wunsch
about: Neues Feature vorschlagen
title: '[FEATURE] '
labels: enhancement
---

## Problem

Welches User-Problem würde dieses Feature lösen?

## Idee

Wie könnte das Feature aussehen? (grob, nicht implementiert)

## Wer braucht das

- Welche Rolle?
- Welche Schul-Größe?
- Auch andere Schulen?

## Alternativen

Was ist der heutige Workaround? Warum reicht der nicht?

## Akzeptanz-Kriterien

Wenn das gebaut ist, was muss möglich sein?
- [ ] ...
- [ ] ...

## Komplexitäts-Schätzung

(grob — Tag, Woche, Monat?)