# Normative Standardspezifikation ## Placeholder-Metadaten, Exportverträge und Governance **Version:** 1.0.0 **Stand:** 29.03.2026 **Status:** Verbindlicher Standard **Geltungsbereich:** Alle bestehenden, neuen und zukünftigen Platzhalter des Systems --- ## 1. Normativer Status Dieses Dokument ist **keine bloße Projektbeschreibung**, sondern eine **verbindliche Standardspezifikation** für das Placeholder-System. Es gilt für: - alle aktuell existierenden Platzhalter, - alle künftig neu eingeführten Platzhalter, - alle technisch abgeleiteten Exportformate, - alle Prompt-, Pipeline- und Analyseverwendungen, die auf Placeholders zugreifen, - alle künftigen Erweiterungen der Placeholder-Registry, des Data Layers und der Exportfunktionen. ### 1.1 Verbindlichkeit Alle neuen und geänderten Placeholder-Implementierungen **müssen** dieser Spezifikation entsprechen. Abweichungen sind nur zulässig, wenn sie: 1. explizit dokumentiert, 2. versioniert, 3. mit `known_issues` und/oder `deprecated` markiert, 4. und in einem Gap- oder Decision-Log nachvollziehbar begründet werden. ### 1.2 Vorrang Diese Spezifikation hat Vorrang vor: - unvollständigen Altbeschreibungen, - impliziten Verhaltensannahmen in Legacy-Prompts, - nicht dokumentierten Exportkonventionen, - informellen Teamabsprachen. Wenn bestehender Code oder bestehende Exporte von dieser Spezifikation abweichen, ist die Abweichung als **Legacy-Zustand** zu markieren und über Versionierung/Deprecation zu behandeln. --- ## 2. Zielbild Das System besitzt bereits einen funktionierenden Placeholder-Export und einen Data Layer als Single Source of Truth für Charts, Scores und KI-Platzhalter. Dieser Standard definiert, wie Placeholder künftig **semantisch, technisch und governance-seitig** beschrieben, exportiert und weiterentwickelt werden. Jeder Placeholder muss als **stabiler, dokumentierter API-Vertrag** behandelbar sein. Der Standard verlangt, dass zu jedem Placeholder mindestens folgende Ebenen eindeutig bestimmbar oder explizit als unbekannt markiert sind: 1. **Ist-Wert / Beispielwert** 2. **Technische Herkunft** 3. **Semantischer Vertrag** 4. **Fehlwert- und Ausnahmebehandlung** 5. **Qualitäts-/Confidence-Logik** 6. **Verwendungsnachweise** 7. **Versionierung / Deprecation / Nachfolger** --- ## 3. Verbindliche Architekturprinzipien ### 3.1 Placeholder = API-Vertrag Placeholder sind keine lose Prompt-Hilfe, sondern **stabile API-Verträge**. Semantik, Einheit, Zeitfenster, Rückgabetyp und Fehlwertverhalten müssen dokumentiert und versioniert sein. ### 3.2 Non-breaking first Bestehende Exporte und bestehende Placeholder-Namen dürfen nicht stillschweigend breaking geändert werden. Änderungen an Semantik, Zeitfenster, Einheit oder Rückgabetyp sind: - entweder über neue Versionen, - oder über neue Nachfolger-Platzhalter, - oder über explizite Deprecation-Pfade abzubilden. ### 3.3 JSON vor Freitext Komplexe Metadaten, Rohdaten, strukturierte Diagnosen und technische Hinweise sind primär als JSON bereitzustellen. Freitext darf ergänzen, aber keine strukturierte Pflichtinformation ersetzen. ### 3.4 Zeitfenster explizit Zeitbezogene Placeholder müssen ein explizites Zeitfenster tragen – mindestens als Metadatum. Legacy-Namen ohne eindeutiges Zeitfenster dürfen im Bestand fortbestehen, müssen aber als semantisch unpräzise markiert werden und einen empfohlenen Nachfolger erhalten. ### 3.5 Fehlwerte explizit Fehlende Werte dürfen im strukturierten Export nicht nur als String wie `"nicht verfügbar"` modelliert werden. Verbindlich sind strukturierte Felder wie: - `available` - `value_raw` - `missing_reason` - `missing_value_policy` ### 3.6 Typisierung ist Pflicht Jeder Placeholder muss einem Typ zugeordnet werden: - `atomic` - `raw_data` - `interpreted` - `legacy_unknown` (nur als Übergang) ### 3.7 Data Layer bleibt Single Source of Truth Fachliche Berechnungen dürfen nicht im Exporter dupliziert oder neu erfunden werden. Der Exporter sammelt Metadaten und referenziert technische Herkunft; er ersetzt keine fachlichen Kernfunktionen. ### 3.8 Kein stilles Raten Wenn technische Herkunft, Zeitfenster, Ausnahmebehandlung oder sonstige Metadaten nicht sicher aus dem Code bestimmbar sind, muss der Zustand als `unknown`, `not_resolved` oder `partially_resolved` markiert werden. ### 3.9 Zukunftsgeltung Jeder neue Placeholder **muss vor produktivem Einsatz** in Registry, Export und Katalog vollständig gegen dieses Dokument validiert werden. --- ## 4. Geltungsbereich und Pflichtanwendung ### 4.1 Diese Spezifikation gilt für - bestehende produktive Placeholder, - neue Placeholder in aktiver Entwicklung, - experimentelle Placeholder, sobald sie außerhalb eines reinen Dev-Modus verwendet werden, - Placeholder in Multi-Stage-Pipelines, - Placeholder in Reports, Dashboards, Prompt-Templates und Exporten. ### 4.2 Diese Spezifikation gilt auch für - neue Goal-/Score-/Correlation-/Driver-Placeholder, - künftige Trainingstyp-/Subcategory-Placeholder, - Placeholder für Diagnose-, Risiko- und Recovery-Logik, - technische Export-Erweiterungen, - Two-Stage-Artefakte. ### 4.3 Nicht zulässig ohne Standardkonformität Nicht zulässig ist: - ein neuer Placeholder ohne dokumentierten Semantikvertrag, - ein neuer Placeholder ohne Zeitfenster-Metadatum, - ein strukturierter Placeholder ohne definierten Output-Typ, - ein produktiver Placeholder ohne dokumentierte Fehlwertbehandlung, - ein interpretierter Placeholder ohne Kennzeichnung als solcher. --- ## 5. Scope des technischen Auftrags ### 5.1 In Scope Der Coding Agent soll: 1. alle existierenden Placeholder inventarisieren, 2. die Metadaten je Placeholder technisch erheben oder als unresolved markieren, 3. einen erweiterten Export erzeugen, 4. einen menschenlesbaren und maschinenlesbaren Katalog erzeugen, 5. die Katalog-/Exportstruktur so implementieren, dass sie **für alle zukünftigen Placeholder wiederverwendbar** ist, 6. Tests und Validierungen ergänzen, 7. Gap-Reports für nicht automatisch auflösbare Metadaten erzeugen. ### 5.2 Out of Scope Nicht gefordert ist: - sofortige komplette fachliche Neudefinition aller Legacy-Placeholder, - sofortige Umbenennung aller problematischen Namen, - Umsetzung aller in anderen Dokumenten vorgeschlagenen neuen Wunsch-Placeholder, - Neuimplementierung des gesamten Prompt-Systems. ### 5.3 Zukunftsanforderung Die technische Lösung muss so gebaut sein, dass **jeder zukünftige Placeholder** denselben Katalog- und Exportmechanismus automatisch oder mit minimalem Zusatzaufwand durchlaufen kann. --- ## 6. Ziel-Deliverables ### 6.1 Code / Export 1. **Erweiterter Placeholder-Export** - neuer Endpoint, CLI, Service-Funktion oder Exportmodus - Legacy-Export bleibt kompatibel 2. **Zentrales Metadatenmodell / Registry-Erweiterung** - wiederverwendbar für bestehende und zukünftige Placeholder 3. **Validierungslogik für neue Placeholder** - technische Prüfung gegen dieses Dokument ### 6.2 Dateien / Dokumentation 4. `PLACEHOLDER_CATALOG_EXTENDED.json` 5. `PLACEHOLDER_CATALOG_EXTENDED.md` 6. `PLACEHOLDER_EXPORT_SPEC.md` 7. `PLACEHOLDER_GAP_REPORT.md` 8. optional: `PLACEHOLDER_VALIDATION_REPORT.md` ### 6.3 Tests 9. Tests für: - Vollständigkeit des Exports, - Konsistenz der Metadaten, - Legacy-Kompatibilität, - Referenzierbarkeit der Verwendungen, - Pflichtfeld-Validierung für neue Placeholder, - normkonforme Typisierung und Zeitfenster-Markierung. --- ## 7. Verbindliches Metadaten-Schema pro Placeholder Jeder Placeholder im erweiterten Export muss mindestens die folgenden Felder besitzen oder explizit als `unknown`/`null`/leer markiert sein. ```json { "key": "weight_aktuell", "placeholder": "{{weight_aktuell}}", "category": "Körper", "type": "atomic", "description": "Aktuelles Gewicht in kg", "semantic_contract": "Letzter verfügbarer Gewichtseintrag des Profils, keine Mittelung", "unit": "kg", "time_window": "latest", "output_type": "number_or_string", "format_hint": "85.8 kg", "example_output": "85.8 kg", "value_display": "85.8 kg", "value_raw": 85.8, "available": true, "missing_reason": null, "missing_value_policy": { "legacy_display": "nicht verfügbar", "structured_null": true, "reason_codes": ["no_data", "insufficient_data", "resolver_error"] }, "exception_handling": { "on_error": "return_null_and_reason", "notes": "Keine Exception bis in Prompt-Ebene durchreichen" }, "quality_filter_policy": null, "confidence_logic": { "supported": false, "notes": "Für latest-Werte nicht erforderlich" }, "source": { "resolver": "get_latest_weight_placeholder", "module": "placeholder_resolver.py", "function": "get_latest_weight", "data_layer_module": "body_metrics.py", "source_tables": ["weight_log"] }, "dependencies": ["profile_id"], "used_by": { "prompts": ["gesamt", "koerper"], "pipelines": ["pipeline", "wettkampf-analyse"], "charts": [] }, "version": "1.0.0", "deprecated": false, "replacement": null, "known_issues": [], "notes": [] } ``` ### 7.1 Pflichtfelder Pflichtfelder sind: - `key` - `placeholder` - `category` - `type` - `description` - `semantic_contract` - `unit` - `time_window` - `output_type` - `value_display` - `available` - `missing_value_policy` - `source` - `version` - `deprecated` ### 7.2 Erlaubte Werte für `type` - `atomic` - `raw_data` - `interpreted` - `legacy_unknown` ### 7.3 Erlaubte Werte für `time_window` - `latest` - `7d` - `14d` - `28d` - `30d` - `90d` - `custom` - `mixed` - `unknown` ### 7.4 Erlaubte Werte für `output_type` - `string` - `number` - `integer` - `boolean` - `json` - `markdown` - `date` - `enum` - `unknown` --- ## 8. Exportformat ### 8.1 Legacy-Export bleibt erhalten Der bestehende Export bleibt unverändert nutzbar. ### 8.2 Neuer erweiterter Export Zusätzlich muss ein erweiterter Export existieren, z. B. mit: - `legacy` - `metadata.by_category` - `metadata.flat` - `metadata.summary` - `metadata.gaps` - `metadata.schema_version` ### 8.3 Zukunftsfähigkeit Der erweiterte Export muss so strukturiert sein, dass neue Placeholder ohne Redesign der Gesamtstruktur ergänzt werden können. --- ## 9. Pflichtregeln für neue und zukünftige Placeholder Jeder neue Placeholder muss vor Freigabe folgende Fragen beantworten können: 1. Was ist die exakte fachliche Semantik? 2. Welches Zeitfenster gilt? 3. Welcher Typ liegt vor? 4. Was ist der Output-Typ? 5. Welche Datenquelle/Funktion berechnet ihn? 6. Wie werden fehlende Werte dargestellt? 7. Welche Ausnahmebehandlung gilt? 8. Welche bekannten Grenzen/Issues gibt es? 9. Wird ein Quality-Filter angewendet? 10. Ist der Placeholder in Prompts/Pipelines referenziert? Wenn eine dieser Fragen unbeantwortet bleibt, darf der Placeholder nicht als voll standardkonform gelten. --- ## 10. Legacy-, Deprecation- und Abweichungsregeln ### 10.1 Legacy-Markierung Bestehende problematische Placeholder dürfen als Legacy bestehen bleiben, wenn sie markiert werden durch: - `deprecated: true/false` - `known_issues` - `replacement` - dokumentierten Semantikhinweis ### 10.2 Deprecation-Pflicht Wenn ein Placeholder semantisch unpräzise, technisch instabil oder fachlich überholt ist, muss ein Deprecation-Pfad vorgesehen werden. ### 10.3 Abweichungsprozess Abweichungen von diesem Standard müssen in einem Decision-/Gap-Log dokumentiert werden, mit: - Begründung, - Impact, - geplanter Nachbesserung, - Verantwortlichkeit. --- ## 11. Validierung und Governance ### 11.1 Pflichtvalidierungen Für bestehende und neue Placeholder müssen validierbar sein: - Pflichtfeld-Vollständigkeit, - gültige Typisierung, - gültiges Zeitfenster, - dokumentierte Quelle, - dokumentiertes Fehlwertverhalten, - dokumentierte Legacy-/Deprecation-Information. ### 11.2 CI-/Test-Eignung Die technische Lösung soll so gebaut werden, dass künftige Validierungen automatisierbar sind. ### 11.3 Two-Stage-Artefakte Interpretierte Outputs aus Basis-Prompts müssen als `interpreted` gekennzeichnet werden und dürfen nicht als rohe Datenplaceholder ausgegeben werden. --- ## 12. Konkrete Arbeitsanweisung an den Coding Agent Der Coding Agent soll diese Spezifikation als **verbindlichen Standard** behandeln und die Implementierung so auslegen, dass sie: - den aktuellen Bestand vollständig erfasst, - für künftige Placeholder wiederverwendbar ist, - Legacy-Verhalten nicht still bricht, - technische Lücken transparent markiert, - und als Grundlage für zukünftige Placeholder-Governance dient. --- ## 13. Akzeptanzkriterien Die Umsetzung gilt nur dann als erfolgreich, wenn: 1. alle existierenden Placeholder im erweiterten Katalog enthalten sind, 2. der Legacy-Export weiter funktioniert, 3. das Metadatenmodell für neue Placeholder wiederverwendbar ist, 4. Pflichtfelder validiert werden, 5. unresolved Informationen sauber markiert werden, 6. die Dokumentation ausdrücklich festhält, dass der Standard **für alle neuen und zukünftigen Placeholder** gilt. --- ## 14. Schlussregel Ab Inkrafttreten dieses Dokuments ist ein neuer Placeholder ohne Standardkonformität nur als explizit dokumentierte Ausnahme zulässig. Der Default ist Standardpflicht, nicht informelle Flexibilität.