Doku-Review (Juli 2026) — „Ist die Dokumentation ein Meisterwerk?"

Kernaussage. Die Taktano-Doku ist ein starkes Gesellenstück mit Meister-Inseln — noch kein Meisterwerk. Überall dort, wo eine generierte oder je PR kuratierte Sicht existiert (Glossar, ops/+Offene-Punkte, Funktionsumfang, Tests.md, produkt/-Trio, solver.md), ist die Doku frisch, pyramidal und zielgruppen-gerecht — nahe am eigenen Anspruch. Was das Prädikat verhindert, ist genau das, was stark geführte Akteure am meisten brauchen: (1) für die wichtigste geführte Rolle — das Werkstatt-Team — existiert kein einziges Anwender-Dokument; (2) mehrere verbindliche Docs widersprechen dem Code oder sich selbst (operativmodell-Lifecycle, Lastenheft §5.1, design/CLAUDE.md); (3) die Vordertüren (Root-README, HANDOFF-Footer/§8, Roadmap, Timesheet-Summen) sind Wochen stale, während die append-only Logs Mega-Zeilen bis 15.284 Zeichen tragen; (4) das OP-Management führt zwei konkurrierende Quellen der Wahrheit; (5) ~20 Je-PR-Pflichten hängen an Prosa-Disziplin — kein einziges Doku-Gate blockiert. Befunde D1–D10 + priorisierte Empfehlungen E1–E6 unten; Folge-OP: OP-DOCS-14.

Zielgruppen: Business/Management (Urteil + Prioritäten) · IT-Dev/Architektur (Befunde mit Belegen) · Customer Service (mittelbar: Anwender-Doku-Lücke). Anlass: Nutzer-Auftrag (12.07.2026) — Experten-Review der Dokumentation (inhaltlich · strukturell · Vorgaben) aus Sicht UX + Prozess-Automatisierung für arbeitsteilige Prozesse mit stark geführten Akteuren. Schwester-Review: UX-Review 2026-07 (App); dieses Review prüft die Doku am selben Maßstab.

1. Prüfrahmen & Methode

Geprüft wurde der Stand des Branches claude/docs-review-process-automation-soolri (12.07.2026, APP_VERSION 0.77.0) — alle ~55 Markdown-Dokumente in vier parallelen Tiefen-Reviews (fachlich+Glossar · architektur/ · betrieb/+produkt/+Logs · Konventionen/Governance), jeweils mit Code-Stichproben (server/src/operativ/*.ts, version.ts, Migrationen, CI-Workflows, check-doc-consistency.sh) und mechanischen Messungen (Zeilenlängen, Marker-Zählung, Format-Matrix über alle 16 architektur/-Docs, gen-ops-Diff).

Bewertungsmaßstab sind die eigenen fünf Meisterwerk-Kriterien (CLAUDE.md): pyramidal · zielgruppen-gerecht · visuell wo es trägt · selbsterklärbar/konsistent (OP-DOCS-9) · True-North-Bezug — plus die Führungs-Lens: Leitet die Doku einen anzuleitenden Akteur (Werker, Support, neuer Dev, KI-Agent) von selbst zum richtigen nächsten Schritt?

2. Was bereits Meisterwerk-Niveau hat

#	Stärke	Beleg
S1	Generierte Single-Source-Sichten funktionieren: Glossar (glossar.mjs → Seite + Sprechblasen, hart validiert), ops/*.md → Offene-Punkte.md (Regenerierung ergibt null Diff), Issue-Spiegel; Funktionsumfang.md und Tests.md sind taggleich frisch (v0.77.0/OP-R7-16 bereits drin; alle 36+3 test:*-Scripts gelistet).	scripts/gen-ops.mjs · docs/betrieb/Funktionsumfang.md · Tests.md
S2	Ehrliche Selbstdiagnose + Status-Ehrlichkeit als Kultur: das Doku-UX-Konzept (OP-DOCS-13) benennt die eigenen Schwächen messerscharf; „bewusst NICHT"-Abschnitte, dormant-Muster, „Arbeitshypothese, nicht belegt"-Marker in produkt/.	Doku-UX-Konzept.md §1 · Bildbewertung.md · Markt-und-Markteintritt.md
S3	Pyramiden-Vorbilder existieren: solver.md (Antwort zuerst, Vergleichstabelle, Demo-Trade-off), Flow-Analyse.md („Ergebnis vorweg" + Code-Belege), Doku-und-Kommentare.md (einziges architektur/-Doc mit Anwender-Abschnitt), das produkt/-Trio.	fachlich/solver.md · architektur/Doku-und-Kommentare.md
S4	Prozess-Automatisierung ist real, nicht Prosa: SessionStart-Hook injiziert die Pflichten maschinell; merge=union + smooth-logs + sync-pr-logs.yml + Auto-Build-Stempel lösen das Parallel-PR-Problem mechanisch.	scripts/session-start-hook.sh · agents.md §6.6
S5	Entscheidungs-Hygiene: E-IDs mit Datum + Begründung (E-CRUD, E-TENANT, E-BACKUP), Feld-Anker // F## im Code, deklarierte Doc-Beziehungen („Zielarchitektur vs. Migrationsweg").	Entitaeten-Lebenszyklus.md · Mandantenfaehigkeit.md
S6	Navigations-Überbau: Lesepfade für 7 Rollen, Doku-Landkarte, Glossar-Sprechblasen, Site-Suche — die Infrastruktur für Zielgruppen-Führung steht.	zielgruppen/Lesepfade.md · docs/README.md

3. Warum es (noch) kein Meisterwerk ist — Befunde D1–D10 (nach Schweregrad)

ID	Befund	Schwere	Bezug
D1	Für Anwender existiert keine Anwender-Doku — der Lesepfad führt aufs falsche Material	🔴 strukturell	OP-DOCS-4
D2	Verbindliche Docs widersprechen Code/sich selbst (Lifecycle, Detailverträge, E-TENANT-1)	🔴 Konsistenz	OP-DOCS-9
D3	Vordertüren stale, Logs unlesbar (README · HANDOFF-Footer/§8 · Roadmap · Timesheet · Mega-Zeilen)	🔴 Lebendigkeit	OP-DOCS-13 / OP-PM-2
D4	Doppelte Wahrheit im OP-Management (HANDOFF §4 vs. ops/*.md)	🔴 Prozess	OP-DOCS-11
D5	Regelwerk ohne Zähne: ~20 Prosa-Pflichten je PR, kein blockierendes Doku-Gate, übertreibende Erfolgs-Behauptungen	🟠 Governance	OP-DOCS-9/-13
D6	architektur/: eigener Format-Standard in 0/16 voll erfüllt, 3 Docs zu Slice-Changelogs degeneriert	🟠 Format	OP-DOCS-13
D7	Glossar-Lücken bei Alltagsbegriffen + Doppel-Glossar (Lastenheft §13 widerspricht §6.4)	🟠 Selbsterklärbarkeit	OP-DOCS-10
D8	Prozesse gebaut, aber nicht gelebt (Meetings, Risikoregister-Prüfdaten, Tests-Sammellauf)	🟠 Compliance	—
D9	Politur: defektes Mermaid, tote Backtick-Pfade, Hex im Lastenheft-Diagramm, Register-Fehlzuordnungen	🟡 Hygiene	OP-DOCS-9
D10	Onboarding-Last: ~2.050 Zeilen Pflichtlektüre, Hook deckt nur ~6 von ~20 PR-Pflichten	🟡 Anleitung	—

D1 · Keine Anwender-Doku (größte strukturelle Lücke). Der Anwender-Lesepfad (Lesepfade.md §nutzer) besteht aus einem Marketing-Doc, dem veralteten operativmodell.md (s. D2) und „Lastenheft §5.1" — einem Spec-Text mit 1.600-Zeichen-Zeilen, OP-IDs und Code-Symbolen (istAbnahmebereit()). Kein Dokument im Repo ist in Sprache/Tiefe des Werkstatt-Teams geschrieben (Grep: kein Handbuch/Tutorial/How-to); das In-App-Onboarding (OP-ONBOARD-1 Slice 1) fängt Erstbesuche ab, ersetzt aber kein Nachschlagewerk („Wie melde ich einen Klärfall?" in 3 Schritten). Für stark geführte Akteure verfehlt die Doku damit ausgerechnet ihre am stärksten geführte Rolle — obwohl sieben Leserkreise verbindlich benannt sind. Auch Customer Service erbt die Lücke (der Lesepfad verweist auf dieselben Spec-Texte).

D2 · Verbindliche Docs widersprechen Code oder sich selbst. Fünf belegte Fälle: (a) fachlich/operativmodell.md §2/§3 zeigt den abgelösten Lifecycle unbestaetigt → aktiv → … als Gegenwart — der Code kennt geplant → angeliefert → in_arbeit ⇄ pausiert → … und migriert unbestaetigt explizit weg (do-state-migrations.ts); das Doc speist zudem den Assistant-RAG-Index (veraltete Antworten im In-App-Chatbot). (b) Lastenheft §5.1 (Master-Spec!): State-Diagramm + Tabelle unterschlagen abgebrochen und nacharbeiten — beides im Code und in §11 desselben Docs. (c) design/CLAUDE.md („Detailvertrag", von CLAUDE.md verbindlich referenziert) beschreibt den Alt-Client: „Tailwind (CDN)", STATUS_HEX, „~1.200-Zeilen-Monolith zerlegen" — real: Tailwind v4, 35 Komponenten, kein STATUS_HEX. (d) E-TENANT-1: Persistenz.md sagt „offen, voller D1-Sink empfohlen", Mandantenfaehigkeit.md sagt „entschieden (C): kein voller Sink" — gegensätzliche Bauanweisungen mit Datenschutz-Folge. (e) CLAUDE.md §Observability behauptet „heute noch console-basiert", obwohl Observability.md die Wrapper-/OTLP-Migration inkl. CI-Gate als gebaut dokumentiert. Genau die Drift-Klasse, die OP-DOCS-9 verhindern soll — an den verbindlichsten Stellen.

D3 · Vordertüren stale, Logs unlesbar. Root-README.md: „Angular 17", wrangler@3-Begründung, 5 statt 36 Tests, Footer „25.05.2026" (vor Repo-Start). HANDOFF.md-Footer: „Letztes Update: 16.06.2026 … Angular 20"; §8 zeigt einen flachen docs/-Baum, den es seit Wochen nicht mehr gibt — entgegen der eigenen §9-Pflege-Pflicht. Roadmap.md: Kernaussage „Heute (2026-06-28)", 4-Wochen-Plan läuft aus, der 🔴-priorisierte OP-VERTRIEB-2 und der Pilot-Meilensteinplan (OP-VERTRIEB-3, Probebetrieb Ende Juli!) fehlen. Timesheet.md: drei widersprüchliche Σ-Zeilen direkt untereinander, KW-Summary endet bei KW26, jüngste Sessions ohne Stop-Zeile. CHANGELOG.md: 70× „(PR folgt)" (inkl. der frisch gemergten #443–#445), doppelter Tages-Header. Und die Mega-Zeilen sind trotz OP-DOCS-13 Phase 4 nicht gebannt: HANDOFF hat 90 Zeilen > 2.000 Zeichen (Max 15.284, OP-OPT-1 ×2 near-identisch), CHANGELOG 107, Lastenheft §11 67 Zeilen > 600 Zeichen (Max 4.405). Die „zuerst lesen"-Dokumente sind die am schwersten lesbaren des Repos.

D4 · Doppelte Wahrheit im OP-Management. Register.md erklärt HANDOFF §4 zur „lebenden Vollliste" (maßgeblich), ops/README.md erklärt ops/*.md zur „maschinenlesbaren Quelle der Wahrheit" — beide gleichzeitig. Der verbindliche Neu-OP-Prozess (agents.md §6.2) kennt das ops/-Format nicht; migriert sind 5 von ~210 OP-IDs; Ergebnis ist nachweisbare Dreifach-Buchführung (OP-VERTRIEB-2 in HANDOFF §4 und Lastenheft §11.6 und ops/). Zusätzlich konkurrieren unter derselben ID OP-DOCS-11 zwei Zielarchitekturen: Doku-UX-Konzept Phase 5 (src/op/op.mjs → generiert HANDOFF §4/Register/IDs) vs. der gebaute Gold-Standard (ops/*.md → Offene-Punkte). Ein geführter Agent, der einen OP parkt, bekommt zwei widersprüchliche verbindliche Anleitungen.

D5 · Regelwerk ohne Zähne + übertreibende Erfolgs-Behauptungen. ~20 verbindliche Je-PR-Pflichten, verstreut über ≥5 Orte (einige existieren nur als Tabellenzelle, z. B. die Funktionsumfang-Pflicht in docs/README.md); es gibt weder ein PR-Template noch eine kanonische Checkliste. Automatisiert-blockierend ist davon nichts: der CI-Job doc-consistency hängt nicht am ci-gate, check-doc-consistency.sh endet immer mit Exit 0, sogar der „hart fehlschlagende" gen-ops-Check ist folgenlos. Dazu behauptet die Doku mehr, als die Mechanik hält: „onBrokenLinks: throw bleibt das Broken-Link-Gate" (real: warn + ignore); „Footer schließt alle Sackgassen" (gilt nur auf der Docusaurus-Site — im Markdown auf GitHub, dem erklärten Primärkanal, sind 0/16 architektur/-Docs rückverlinkt); „Log-Zeilenlängen-Warnung, OP-ID-Existenz" als Governance genannt, im Skript nicht vorhanden. Dass Compliance trotzdem oft klappt (S1), liegt an Nachahmung guter Vorbilder — nicht am System.

D6 · architektur/ erfüllt den eigenen Format-Standard nicht. Format-Matrix über alle 16 Docs: 0/16 mit vollem Status-Header (Status/Bezug/Zielgruppe/True-North, wie ihn das Doku-UX-Konzept vorlebt), 7/16 ohne Kernaussage-Block (und 4 weitere mit abweichenden Formaten — vier konkurrierende Kopf-Muster), 11/16 ohne benannte Zielgruppe, 8/16 ohne Diagramm (auch wo eines klar trüge: Mandantenfähigkeit, Backup-Restore, Observability). Drei Docs sind zu Slice-Changelogs degeneriert — In-App-Assistent.md (491 Z.) trägt im Kopf gleichzeitig „Design-Stand vor der Umsetzung (kein Code)" und „Status: Slices 1–6 umgesetzt"; Audit-Log.md sagt in §2.1 „Heute ist alles ein DO-Blob; D1 noch nicht verdrahtet" und in §Slices „D1 ✅ aktiv". Geführte Leser können „gebaut" und „geplant" nur archäologisch trennen.

D7 · Glossar-Lücken + Doppel-Glossar. Im Glossar (57 Einträge) fehlen genau die Begriffe, die geführte Akteure täglich treffen: Klärfall/Klärung, Phase, Leistung, Terminklasse, Angebotsmodus, Auslastung (True-North-Frage 1 selbst!), Nachkontrolle, Helfer; zugleich sind TAM/SAM/SOM, ARPA, Beachhead als „Fachlich (Werkstatt)" gelabelt. Parallel führt Lastenheft §13 ein zweites Glossar mit Leichen: „Helfer = anderer geforderter Skill" widerspricht §6.4 desselben Dokuments („kein distinkter Helfer-Skill mehr"), „Standort = abgeleitet aus laufendem Teilschritt" widerspricht §4.3 (Ist-Belegung).

D8 · Prozesse gebaut, aber nicht gelebt. Der Meeting-Prozess (Vorlage in Meisterwerk-Qualität) wurde beim ersten echten Anlass — dem Gründer-Call 07-08 mit Rollout-Beschlüssen — nicht genutzt (Index: „noch keine Protokolle"); die Erst-Notiz enthielt prompt den falschen Pilotkunden-Namen („Festler" statt Vest), den ein Protokoll mit Review wohl abgefangen hätte. Risikoregister: 6 von 18 Risiken tragen „Letzte Prüfung 2026-06-24" trotz ~30 PRs und Sichtungs-Pflicht seither (Sichtung ohne Datums-Stempel ist von „vergessen" nicht unterscheidbar). Tests.md §6-Sammellauf lässt 3 Tests aus, die §1 selbst listet.

D9 · Politur. Defektes Mermaid-Diagramm (Operative-Durchgaengigkeit.md §Werker-Sicht, maschinell verifiziert: Parse-Error); fünf tote docs/…-Backtick-Pfade (Bildbewertung ×2, Kosten, Seed-Plan ×2 — vom Linkcheck unerfasst, da kein Markdown-Link); Hardcoded-Hex im Lastenheft-Mermaid (§5.2-classDefs) entgegen „Never hard-code hex"; Register.md linkt OP-DOCS-1…-12 pauschal auf agents.md §5.1 (besitzt nur OP-DOCS-9) und OP-PM-1 auf §6.6 (behandelt ihn nicht); veraltete Link-Labels (docs/datamodel.md); Lastenheft-Kopf „Stand: 25.05.2026" trotz Einträgen vom 07-12.

D10 · Onboarding-Last. Pflichtlektüre vor der ersten Aktion: HANDOFF (585 Z., mit 15k-Zeilen) → Lastenheft (1.131 Z.) → agents.md (334 Z.) ≈ 2.050 Zeilen. Der Hook ist die faktische Kurz-Referenz, deckt aber nur ~6 der ~20 PR-Pflichten. Für Menschen existiert Entwicklungsansatz.md als lesbarer Einstieg (gut); das agenten-taugliche Äquivalent — eine einseitige, vollständige Checkliste — fehlt.

4. Kennzahlen (gemessen, 2026-07-12)

Kennzahl	Wert
HANDOFF.md: Zeilen > 2.000 Zeichen / Maximum	90 / 15.284 (OP-OPT-1, ×2 near-identisch)
CHANGELOG.md: Zeilen > 2.000 Zeichen / „(PR folgt)"-Marker	107 / 70 (davon 3 frisch gemergte #443–#445)
Lastenheft §11: Zeilen > 600 Zeichen / Maximum	67 / 4.405
architektur/ (16 Docs): voller Status-Header / Kernaussage / Zielgruppe / Rück-Link im MD	0/16 · 9/16 · 5/16 · 0/16
Je-PR-Pflichten (verbindlich, verstreut) / davon CI-blockierend	~20 / 0
Parallele OP-Repräsentationen / davon in ops/*.md migriert	8 (HANDOFF §4 · Lastenheft §11 · IDs · Register · Roadmap · ops/ · Offene-Punkte · Issues) / 5 von ~210 IDs
Timesheet: widersprüchliche Σ-Zeilen / fehlende KW-Summaries	3 / KW27+KW28

5. Priorisierte Empfehlungen E1–E6 (Wirkung ÷ Aufwand)

1. E1 · Anwender-Handbuch (D1): neues docs/anwender/ — 1–2 Seiten je Kern-Flow („Mein Arbeitstag", „Klärfall melden in 3 Schritten", „Fahrzeug annehmen"), Werkstattsprache, Bilder/ Diagramme, ohne OP-IDs und Code-Symbole; Anwender- und Support-Lesepfad dorthin umbiegen. Zahlt auf OP-DOCS-4 ein; Quelle kann das In-App-Onboarding („Kurz erklärt"-Texte) sein.
2. E2 · Drift-Fix-Runde „verbindliche Stellen" (D2, D3-Vordertüren): operativmodell.md auf den realen Lifecycle, Lastenheft §5.1 vervollständigen (abgebrochen/nacharbeiten), design/CLAUDE.md auf den Ist-Client, Root-README + HANDOFF-Footer/§8 aktualisieren, Persistenz.md→E-TENANT-1-Entscheid nachziehen, CLAUDE.md-Observability kürzen auf Verweis — danach den Assistant-Doku-Index regenerieren.
3. E3 · OP-Single-Source entscheiden (D4): ops/*.md verbindlich zur Quelle erklären — agents.md §6.2 auf ops/-first umschreiben, HANDOFF §4 als „Archiv/Bestand (nicht mehr führend)" labeln, Migrations-Fortschritt sichtbar zählen (z. B. in Offene-Punkte.md), Doku-UX-Konzept Phase 5 auf das ops/-Muster umschreiben oder als verworfen markieren.
4. E4 · Gates scharf schalten (D5, D3): eine False-Positive-arme Teilmenge des doc-consistency-Checks in den ci-gate heben (gen-ops-Validierung, Offene-Punkte-Staleness, tote Links); onBrokenLinks: 'throw' setzen (oder die Behauptung korrigieren); Zeilenlängen- und Staleness-Warnungen (README-/HANDOFF-Footer-Datum, Timesheet-Σ) ergänzen; den „Zur Landkarte"-Footer zusätzlich statisch ins Markdown generieren (Glossar-Generator-Muster) statt nur ins Site-HTML.
5. E5 · Eine kanonische PR-Checkliste (D5, D10): alle Je-PR-Pflichten an einem Ort (.github/PULL_REQUEST_TEMPLATE.md + Hook, idealerweise aus einer Quelle generiert); Streu-Pflichten (Funktionsumfang, Roadmap) dort aufnehmen; CLAUDE.md/agents.md verweisen statt wiederholen.
6. E6 · Format-Standard + Alltagsbegriffe (D6, D7): den 4-teiligen Status-Header (Status/Bezug/Zielgruppe/True-North) + Kernaussage-Block als Template in agents.md §2.1 festzurren und per Warn-Gate prüfen; Slice-Historien in einen Anhang/CHANGELOG auslagern; Glossar um ~10 operative Begriffe ergänzen und Lastenheft §13 auf einen Glossar-Verweis eindampfen.

Folge-OP für die Umsetzung: OP-DOCS-14 (ops/OP-DOCS-14.md) — bündelt E1 + E2 + E4 (bestes Wirkung-÷-Aufwand-Verhältnis). E3 läuft unter OP-DOCS-11, E6-Format unter OP-DOCS-13 weiter.

6. True-North-Bezug

Dieses Review beantwortet keine der drei Leitfragen selbst — es bedient die „schneller/genauer"- Klausel: Es macht messbar, wo die Doku die Antworten verlangsamt (stale Vordertüren, Mega-Zeilen, fehlende Anwender-Sprache) oder verfälscht (Lifecycle-Drift bis in den RAG-Index des In-App-Assistenten), und priorisiert die Schritte, die die Doku wieder zur verlässlichen Antwortquelle machen. Querverweise: Doku-UX-Konzept (OP-DOCS-13) · UX-Review 2026-07 · Sanity-Checkliste.

---

↩ Zurück zur Doku-Landkarte · verwandt: Lesepfade · Doku-UX-Konzept · agents.md