Doku- & Doku-Vorgaben-Review (Stand v0.164.1, 2026-10-16)
Zielgruppen: Business/Management (Kernaussage + Verdikte) · IT-Dev/Doku-Pfleger (Befunde mit Beleg). Gegenstand: Die Dokumentation selbst — Inhalt, Struktur und die Doku-Vorgaben (CLAUDE.md-Leitprinzip „Dokumentation als Meisterwerk": pyramidal · zielgruppen-gerecht · visuell · konsistent). Schwester-Review zur App:
UX-Prozess-Review-2026-10.md. Methode: Delta-Audit v0.150.0 → v0.164.1 (14 Minor-Versionen, 89 Commits aufmain). Zwei Achsen: (1) Doku↔Doku (Stand-Stempel, Testzahl, Entscheidungs-Fragmente, Landkarte, Glossar) inkl.scripts/check-doc-consistency.sh; (2) Doku↔Code — stimmen Routen, Audit-Aktionen und Begriffe, und ist das seit v0.150.0 Gebaute (Dexman: Monatsbericht, Festschreibung, Plausibilitäts-Hinweise, Monatsmeldung, Vorschläge, Anzeige-Raster, Kachel · Fragenkataloge · SPA-Fallback · Lazy-Routen) dokumentiert. Die Code-Seite wurde mechanisch gegen den Quelltext geprüft (Routen, Audit-Aktionen, Landkarte), nicht aus der Erinnerung. Bezugspunkt & Gültigkeit (MED-D-97): v0.164.1 · Commitb1978f5(Basismain) + PR dieser Ausgabe · 2026-10-16. LöstDoku-Review-2026-09.md(Bezugspunkt v0.150.0) ab; der Doku-Backlog dort (MED-OP-DOKU-9/10) war leer. Nächster Doku-Audit gemäß Stale-Regel (agents.md§6.7).
1. Kernaussage
Die Doku-Mechanik hält: keine handgepflegten Versionsnummern mehr, gemessene Testzahlen, ein Entscheidungs-Fragment je Dexman-PR — und die langsamen Rahmen-Docs sind wieder die Stelle, an der es driftet. Sechs neue Befunde (B61–B65, B67) und ein Hinweis (B66): vier davon klein und in dieser Runde behoben; zwei (Katalog der Audit-Aktionen, tote Links der veröffentlichten Doku-Site) sind eigene Vorhaben und als Issues geführt. Die Wurzelursache ist dieselbe wie in den Vorrunden: was ein PR baut, steht im Log-Fragment, aber die Übersichts-Docs (API-Tabelle, Landkarte, Glossar) werden nicht im selben PR angefasst.
| Achse | Verdikt |
|---|---|
| Stand-Stempel — keine Versionsnummer mehr in lebenden Docs (MED-D-363); Rückfall-Wächter im Doku-Check | ✅ |
Testzahl — gemessen, nicht gepflegt (scripts/testzahlen_messen.py, MED-D-701): 1143 Tests / 98 Dateien (Server) · 117 / 31 (E2E: 91 gemockt + 26 Full-Stack); Vitest meldet 1144 — die Differenz von 1 ist die bekannte Grenze der statischen Zählung (ein it in einer Schleife zählt einmal) | ✅ (B66, Hinweis) |
Entscheidungs-Fragmente — für #683 · #684 · #693 · #694 · #699 · #700 · #735 · #736 · #737 · #749 · #754 · #764 je eine Datei in entscheidungen.d/ | ✅ |
Dexman Doku↔Code — Systementwurf §10.6–§10.10 und Dexman.md decken Monatsbericht, Festschreibung, Vorschläge, Raster, Kachel (inkl. „Umsatz vs. Plan") ab | ✅ |
| API-Tabelle Dexman-Systementwurf §6.5 | 🟡 → ✅ (B61) |
Landkarte docs/README.md führt alle Doku-Dateien | 🟡 → ✅ (B62) |
| Glossar neue sichtbare Begriffe | 🟡 → ✅ (B63) |
| Feature-Liste deckt die seit v0.150.0 gebauten Dexman-Funktionen | 🟡 → ✅ (B64) |
| Katalog der Audit-Aktionen (G-4, True North 3) | ⛔ offen → Issue (B65) |
| Doku-Site — Docusaurus-Build besteht, meldet aber tote Links auf 3 Seiten | 🟡 offen → Issue (B67) |
2. Was gehalten wurde (bewahren)
- Fragmente statt Hot-Files (MED-D-359/701): kein PR dieser Runde hat
CHANGELOG.md,HANDOFF.md,Decision-Log.md,Timesheet.mdoderTest-Uebersicht.mdangefasst; die Merge-Konflikte, die diese Dateien früher erzeugten, sind weg. - Annahmen werden gekennzeichnet statt festgeschrieben: „Umsatz vs. Plan" (Schwellen 5 % / 15 %) und „Top-Reserve"
(= größte Wirkung) stehen als Annahme in
Dexman.mdund im Systementwurf und als Bestätigungspunkt in #764. - Dexman-Doku ist pyramidal und hat die Zustandsdiagramme dort, wo sie tragen (Vorschlags-Workflow §10.9).
3. Befunde
| # | Befund | Beleg | Maßnahme |
|---|---|---|---|
| B61 | API-Skizze des Dexman-Systementwurfs ist veraltet: nennt …/eingaben (real: …/stand) und …/import (nicht gebaut, Excel-Übernahme DEX-13 ist offen) und lässt 9 gebaute Routen aus | Dexman-Systementwurf.md §6.5 gegen server/src/api/app.ts (Dexman-Block) | ✅ Tabelle neu aus dem Code: 16 Zeilen, Hinweis „Excel-Übernahme noch nicht gebaut" |
| B62 | Landkarte führt 4 Docs nicht: Onboarding-Neubau.md, Onboarding-Neubaustudie.md, Zeiterfassung-Segmente-und-Push.md, UX-Prozess-Review-2026-10.md | Abgleich aller docs/**/*.md mit docs/README.md | ✅ Zeilen ergänzt, Audit-Zeilen auf die jeweils neueste Ausgabe |
| B63 | Sichtbare Begriffe „Beratungsmodus" (MED-D-736) und „Beratungsvorschlag" (MED-D-735) fehlen im Glossar | docs-site/src/glossar/glossar.mjs | ✅ beide Einträge, Glossar neu erzeugt (49 Begriffe) |
| B64 | Feature-Liste kennt die Dexman-Funktionen #735 (Vorschläge), #736 (Raster), #737 (Kachel) nicht — die Issues trugen nur offener-punkt | feature.d/ ohne Eintrag; Issues ohne Label Feature-Liste | ✅ drei Fragmente in feature.d/, Label Feature-Liste an #735/#736/#737 |
| B65 | 67 von 119 Audit-Aktionen aus dem Code stehen in keinem Doc; Audit-Log.md beschreibt das Modell, nicht die Ereignisse | aktion: '…'-Literale in server/src/ gegen docs/ und CLAUDE.md | Issue #773 — Katalog erzeugen statt pflegen (G-2) |
| B66 | Statische Testzählung weicht um 1 von Vitest ab (1143 gegen 1144) | scripts/testzahlen_messen.py --pruefen gegen vitest run | Hinweis; die Grenze ist im Skript dokumentiert, kein Handlungsbedarf |
| B67 | Docusaurus-Build meldet tote Links: HTML-Anlagen (Dexman-Prototyp.html, Akten-Cockpit-Handoff) liegen außerhalb der Site, die HANDOFF-Kopie unter /projekt/ hat repo-relative Pfade | npm run build in docs-site/; der Doku-Check sieht sie nicht | Issue #775 — Site-Auslieferung bzw. Link-Umschreibung klären |
Wurzelursache: Übersichts-Docs mit handgepflegten Listen (API-Tabelle, Landkarte, Glossar, Feature-Liste) driften, weil der PR, der etwas baut, nur seine Fragmente anlegt. Wo die Liste erzeugt wird (Feature-Liste aus Fragmenten, Testzahlen gemessen), tritt die Drift nicht auf. Empfehlung (Teil von MED-OP-REVIEW-1, kein neuer OP): Listen, die sich aus dem Code ableiten lassen — Routen, Audit-Aktionen — erzeugen statt pflegen; B65 ist der erste Fall.
4. Maßnahmenplan
- B61–B64 — in dieser Runde behoben (PR dieser Ausgabe).
- B65 — Katalog der Audit-Aktionen erzeugen und im Doku-Check absichern (#773). B67 — tote Links der Doku-Site (#775).
- Offene fachliche Bestätigung aus der Dexman-Kachel: Schwellen für „Umsatz vs. Plan" und die Auslegung „Top-Reserve" (#764) — Doku nennt sie als Annahme.
- Nächster Doku-Audit: spätestens bei v0.174.x oder nach 90 Tagen (Stale-Regel).
Dieses Audit ist ein Zeitdokument (MED-OP-REVIEW-1 / agents.md §6.7): Bezugspunkt v0.164.1 · Commit b1978f5 ·
2026-10-16. Befunde werden als Issues geführt (B65 → #773, B67 → #775), nicht im Audit abgearbeitet; die hier behobenen kleinen
Befunde (B61–B64) stehen im selben PR. Keine Versionsänderung durch diese Ausgabe.