mitai-jinkendo/.claude/docs/audit/platzhalter/audit-report-2026-03-29/01_EXECUTIVE_SUMMARY.md

Placeholder-Audit: Executive Summary

Audit-Datum: 29. März 2026 Umfang: 111 Platzhalter (vollständig) Normative Basis: PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md v1.0.0 Audit-Methodik: 4 spezialisierte Agents (Code, Semantik, Zeit/Confidence, Usage) Audit-Dauer: ~590 Sekunden (4 Agents parallel)

---

Compliance-Übersicht

Gesamtergebnis: 7% voll normkonform (8/111)

Compliance-Level	Anzahl	Prozent	Hauptprobleme
Compliant	8	7%	Best-Practice-Beispiele (nutrition_avg, weight_aktuell)
Partially Compliant	22	20%	1-2 Gaps (meist time_window oder confidence)
Non-Compliant	81	73%	3+ kritische Gaps

---

Kritische Zahlen

Systemische Gaps (nach Normative Requirements)

Gap-Typ	Anzahl	Prozent	Norm-Verstoß
time_window: unknown	74	67%	§3.4 "Zeitfenster explizit"
Keine Confidence-Logik	103	93%	§5 "Qualitäts-/Confidence-Logik"
Kein data_layer_module	100	90%	§7 "Source" vollständig
Keine Mindestdaten definiert	99	89%	Implizit in §5
category: Unknown	49	44%	§7.1 "Pflichtfelder: category"
description: "No description"	49	44%	§7.1 "Pflichtfelder: description"
Keine source_tables	90	81%	§7 "Source: source_tables"
metadata_completeness_score: 0	111	100%	Kein Placeholder produktionsreif
schema_status: draft	111	100%	§13 Akzeptanzkriterien

---

Wichtigste Systemische Schwächen

1. Metadaten-Dokumentation fundamental unvollständig

Problem:

• 100% der Platzhalter haben metadata_completeness_score: 0
• 44% ohne fachliche Kategorie ("Unknown")
• 44% ohne Beschreibung ("No description available")
• Kein einziger Platzhalter hat Status "production"

Impact:

• Platzhalter können nicht als stabile API-Verträge genutzt werden
• Prompt-Bibliothek hat keine verlässliche Metadaten-Basis
• Neue Platzhalter haben kein Qualitätsvorbild

Root Cause:

• Export-System generiert Struktur, füllt aber nicht alle Felder
• Keine systematische Dokumentationspflicht im Development-Workflow

---

2. Zeitfenster-Chaos

Problem:

• 67% ohne definiertes Zeitfenster (time_window: unknown)
• Code-Inkonsistenzen:
  • activity_summary: Docs "7d", Code 14d, Metadaten "unknown"
  • weight_trend: Docs "7d/30d", Code 28d, Metadaten "unknown"
• Namen-Metadaten-Mismatch:
  • zeitraum_7d, zeitraum_30d, zeitraum_90d → alle time_window: unknown
  • sleep_avg_duration_7d → time_window: unknown

Impact:

• KI kann Zeitfenster nicht interpretieren
• Reports können nicht korrekt zeitlich einordnen
• Vergleiche zwischen Platzhaltern problematisch

Root Cause:

• Zeitfenster wird oft im Code definiert, aber nicht in Metadaten übertragen
• Keine automatische Extraktion aus Funktionsnamen/Parametern

---

3. Fehlende Confidence-Systeme

Problem:

• Nur 8 Platzhalter (7%) haben Confidence-Logik
• 103 ohne jegliche Datenqualitäts-Signale
• Kritisch bei:
  • Trend-Platzhaltern (slope, delta, change) → keine Warnung bei zu wenig Datenpunkten
  • Score-Platzhaltern (nutrition_score, activity_score) → keine Reliability-Info
  • Korrelations-Platzhaltern → keine Min-Data-Thresholds

Impact:

• KI kann nicht zwischen "sicher" und "unsicher" unterscheiden
• User erhält keine Warnung bei unreliablen Werten
• Prompt-Logik muss blind vertrauen oder eigene Heuristiken entwickeln

Root Cause:

• Nur nutrition_metrics, body_metrics, activity_metrics haben calculate_confidence()
• Andere Data-Layer-Module ohne Confidence-Pattern

---

4. Unstrukturierte Fehlwertbehandlung

Problem:

• 70 Platzhalter mit "nicht verfügbar"-String statt strukturiertem Format
• Verstoß gegen Norm §3.5 "Fehlwerte explizit"
• Legacy-Only: missing_value_policy.legacy_display: "nicht verfügbar"
• Keine strukturierten Felder: available, value_raw, missing_reason

Impact:

• KI muss String-Parsing betreiben ("nicht verfügbar" vs. "0" vs. "null")
• Keine maschinenlesbare Unterscheidung zwischen Fehlertypen
• Folgeprompts können nicht unterscheiden: Daten fehlen vs. Fehler aufgetreten

Root Cause:

• Historisches Legacy-Format aus v1 des Placeholder-Systems
• Kein strukturierter Refactor durchgeführt

---

5. 67 Platzhalter noch nicht produktiv eingebunden

Status:

• 67 Platzhalter (60%) haben 0 Verwendungen in Prompts/Pipelines/Charts
• Wichtig: Dies ist KEIN Technical Debt, sondern erwartbar bei Prompt-Bibliothek im Aufbau
• Viele in Kategorie "Unknown" (41 von 49 Unknown-Platzhaltern ungenutzt)

Fachliche Klassifizierung (siehe USAGE_ROLE_CLASSIFICATION.md):

• 30 Platzhalter (45%): Explizit in Roadmap Phase 0c/1/2 geplant
  • Scores (6), Correlations (5), Ability Balance (5), Goals Details (11), Sleep Debt, Plateau Detection, Top Drivers
• 37 Platzhalter (55%): Fachlich plausibel, noch nicht in Prompts integriert
  • Body Deltas, Nutrition Details, Training Quality, Focus Category Weights/Progress, Meta/Convenience
• 0 Platzhalter: Redundant oder deprecation-würdig

Interpretation:

• Prompt-Bibliothek ist in Phase 0b/0c (Goals, Data Architecture)
• Phase 1 (Charts), Phase 2 (Correlations) werden 30+ Platzhalter aktivieren
• Kein Deprecation-Bedarf – Integration statt Deletion erforderlich

Next Steps:

• Integration-Timeline für 30 geplante Platzhalter (Phase 0c/1/2)
• Prompt-Use-Cases für 10-15 plausible Platzhalter identifizieren
• Nutzungsrate wird von 40% auf 50-60% steigen (organisch)

---

Größte Risiken für Prompt-Bibliothek und Reporting

1. Breaking-Change-Risiko (🔴 HIGH)

12 produktkritische Platzhalter mit 3-19 Verwendungen:

Placeholder	Uses	Risk	Reason
{{name}}	19	🔴 EXTREM	In 9 Prompts + 10 Pipelines
{{geschlecht}}	14	🔴 EXTREM	Gender-specific Logik in 7 Prompts
{{height}}	12	🔴 EXTREM	BMI-Berechnungen, Body Composition
{{weight_aktuell}}	10	🔴 HOCH	Numerisch sensitiv, Format-Breaking
{{weight_trend}}	10	🔴 HOCH	Code-Docs-Konflikt!
{{goal_bf_pct}}	10	🔴 HOCH	Body Composition Goals
{{caliper_summary}}	8	🟡 MITTEL	Body Fat Summary
{{circ_summary}}	8	🟡 MITTEL	Circumference Summary
{{goal_weight}}	8	🟡 MITTEL	Weight Goals
{{protein_ziel_low/high}}	7	🟡 MITTEL	Nutrition Guidance
{{activity_detail}}	4	🟡 MITTEL	Time-Window unklar!

Mitigation:

• Jede Änderung an diesen 12 erfordert:
  1. Identifikation aller betroffenen Prompts/Pipelines
  2. Koordinierte Migration über alle Templates
  3. Backward-Compatibility-Periode (2-4 Wochen)
  4. Full Regression-Tests

---

2. Code-Dokumentations-Konflikte (🔴 HIGH)

Bekannte Inkonsistenzen:

Placeholder	Description	Code	Metadaten	Status
weight_trend	"7d/30d"	28d	unknown	🔴 KONFLIKT
activity_summary	"7d"	14d	unknown	🔴 KONFLIKT
activity_detail	unklar	14d (default)	unknown	🟡 UNKLAR

Impact:

• Kein Single Source of Truth
• KI nutzt evtl. falsche Zeitfenster-Annahmen
• User-Verwirrung bei Zeit-Interpretation

Mitigation:

• P0 Fix: Code als autoritativ nehmen, Docs/Metadaten aktualisieren
• Automatische Konsistenz-Checks (CI/CD)

---

3. Prompt-Fragility (🟡 MEDIUM)

Problem:

• Platzhalter ohne Zeitfenster → KI kann Perioden nicht interpretieren
• Fehlende Confidence → KI kann Datenqualität nicht bewerten
• "nicht verfügbar"-Strings → KI muss raten ob Fehler oder kein Wert

Beispiel-Szenarien:

Prompt: "Analysiere die Gewichtsentwicklung basierend auf {{weight_trend}}"
Problem: KI weiß nicht, ob 7d, 28d oder 90d → falsche Interpretation möglich

Prompt: "Bewerte die Korrelation {{correlation_energy_weight_lag}}"
Problem: Keine Confidence → KI kann nicht warnen "nur 5 Datenpunkte, unreliabel"

Mitigation:

• Metadata-Enrichment für alle kritischen Platzhalter
• Strukturierte Missing-Value-Policies

---

4. Fehlende Produktions-Governance (🟡 MEDIUM)

Indikatoren:

• 100% Draft-Status → keine produktionsreifen Platzhalter
• 90% ohne Data-Layer-Module dokumentiert
• Keine Validierungslogik für neue Platzhalter
• Keine klaren Production-Ready-Kriterien

Langfristige Konsequenzen:

• Neue Entwickler können nicht erkennen, welche Platzhalter "safe to use" sind
• Keine Guidance für Prompt-Autoren (welche Platzhalter für welchen Use-Case)
• Akkumulation weiterer inkonsistenter Platzhalter

KEIN Technical Debt:

• 60% ungenutzte Platzhalter ≠ "tote Codepfade"
• Prompt-Bibliothek ist im Aufbau (Phase 0b/0c/1/2)
• Ungenutzte Platzhalter sind fachlich geplant oder plausibel

---

Dokumentierte Normkonflikte zwischen Dateien

Konflikt	Quelle 1	Quelle 2	Severity	Resolution
Zeitfenster weight_trend	Description: "7d/30d"	Code: 28d	🟡 MEDIUM	Code ist autoritativ → Docs aktualisieren
Zeitfenster activity_summary	Description: "7d"	Code: 14d	🟡 MEDIUM	Code ist autoritativ → Docs aktualisieren
Neue Platzhalter	requirements_dev.md: 27 neue P1-P27	Extended Catalog: 111 existierend	🟢 INFO	requirements_dev ist Arbeitsdokument, kein Normativ
Bestandszahlen	Export Spec: 116	Gap Report/Catalog: 111	🟢 INFO	5 Platzhalter = Metafelder (schema_version, etc.)

Rangfolgen-Resolution (aus Audit-Auftrag):

1. NORMATIVE.md (höchste Instanz) - Verbindliche Standardspezifikation
2. Code (aktueller Ist-Zustand) - Bei Konflikt Code > Docs
3. Extended Catalog (dokumentierter Stand) - Generated Truth
4. requirements_dev.md (Arbeitsdokument) - NICHT normativ, nur Planning

---

Best-Practice-Modelle identifiziert

Vollständig normkonforme Platzhalter (8):

1. Nutrition Averages (4):

• protein_avg, kcal_avg, fat_avg, carb_avg

Warum Best-Practice:

✅ time_window: 30d (explizit)
✅ aggregation: AVG() via nutrition_metrics.py
✅ min_data: 8 (low), 12 (medium), 18 (high)
✅ confidence_logic: calculate_confidence(data_points, 30, 'general')
✅ missing_value_policy: strukturiert (available=false, reason='insufficient_data')
✅ data_layer_module: nutrition_metrics.py
✅ source_tables: ['nutrition_log']

2. Weight Aktuell (1):

• weight_aktuell

Warum Best-Practice:

✅ time_window: latest
✅ aggregation: Latest entry ORDER BY date DESC LIMIT 1
✅ confidence_logic: high if exists, insufficient if no data
✅ data_layer_module: body_metrics.py
✅ source_tables: ['weight_log']

3. Andere (3):

• weight_trend, circ_summary, age (verschiedene Best-Practice-Aspekte)

---

Audit-Methodik-Transparenz

4 Spezialisierte Agents (Parallel)

1. Code-Evidence-Agent (124s)

• Aufgabe: Vollständige Code-Analyse aller Resolver-Funktionen
• Scope: placeholder_resolver.py (Zeilen 1075-1221), data_layer/*.py, routers/prompts.py
• Output: Technische Herkunft, Source-Tables, Return-Types für alle 111
• Evidence-Level: code_verified (100%)

2. Semantic-Contract-Agent (218s)

• Aufgabe: Fachliche Bedeutung aus Dokumentation ableiten
• Scope: DATA_ARCHITECTURE.md, mitai_jinkendo_konzept_diagramme_auswertungen_v2.md, Extended Catalog
• Output: Description, Category, Semantic Contract für alle 111
• Evidence-Level: documentation_verified (56%), fachlich_abgeleitet (44%)

3. Time-Window-Confidence-Agent (90s)

• Aufgabe: Zeitfenster klassifizieren, Confidence-Patterns identifizieren
• Scope: Code + Catalog + Normative Spec (erlaubte time_window-Werte)
• Output: Zeit-Compliance, Aggregationslogik, Min-Data-Thresholds
• Evidence-Level: code_verified (75 unklar), code_inferred (rest)

4. Prompt-Usage-Agent (157s)

• Aufgabe: Verwendung in Prompts/Pipelines/Charts analysieren
• Scope: ai_prompts table (via Catalog), Grep-Suche nach {{placeholder}}
• Output: Used-By, Criticality, Rename-Risk
• Evidence-Level: catalog_verified (100%)

Konsolidierung:

• Cross-Agent-Validation (4 Perspektiven auf jeden Placeholder)
• Konflikt-Resolution nach Rangfolge (Norm > Code > Catalog > Docs)
• Evidence-Level-Klassifizierung (code_verified > documentation_verified > fachlich_abgeleitet > unclear)

---

Nächste Kritische Schritte

P0 (VOR PRODUCTION - BLOCKING)

1. Zeitfenster-Klassifizierung (74 Platzhalter)

• Aufwand: 8-12 Stunden
• Methode:
  1. Namen-Analyse (*_7d, *_28d, etc.) → automatisch
  2. Code-Analyse (default days-Parameter) → semi-automatisch
  3. Fach-Entscheidung für Unklare (ability_balance, scores) → manuell
• Deliverable: Alle time_window: unknown → gültige Werte (latest/7d/14d/28d/30d/90d/mixed)

2. Code-Docs-Konflikte auflösen (3 Platzhalter)

• Aufwand: 2 Stunden
• Items:
  • weight_trend: Description + Metadaten auf "28d" ändern
  • activity_summary: Description + Metadaten auf "14d" ändern
  • activity_detail: Default-Zeitfenster dokumentieren
• Validation: Automatische Konsistenz-Checks (Code ↔ Catalog)

3. Kategorie + Beschreibung (49 Platzhalter)

• Aufwand: 4-6 Stunden
• Methode: Bulk-Update aus Semantic-Contract-Agent-Report
• Deliverable:
  • Alle category: Unknown → fachliche Kategorien
  • Alle description: "No description available" → aussagekräftige Beschreibungen

---

P1 (THIS SPRINT - HIGH PRIORITY)

4. Confidence-Logik für Trend-/Delta-Platzhalter (11)

• Aufwand: 12-16 Stunden
• Items:
  • weight_28d_slope, weight_90d_slope, weight_7d_median
  • fm_28d_change, lbm_28d_change
  • waist_28d_delta, hip_28d_delta, chest_28d_delta, arm_28d_delta, thigh_28d_delta
  • vo2max_trend_28d
• Pattern: confidence = calculate_confidence(data_points, time_window_days, 'trend')
• Thresholds: high >= 70%, medium >= 50%, low >= 30% data coverage

5. Strukturierte Missing-Value-Policy (70 Platzhalter)

• Aufwand: 8-10 Stunden
• Refactor:
  • Legacy-String "nicht verfügbar" beibehalten (Backward-Compatibility)
  • Zusätzlich strukturierte Felder: available, missing_reason, value_raw
• Deliverable: Dual-Mode-Support (Legacy + Structured)

6. Data-Layer-Module dokumentieren (100 Platzhalter)

• Aufwand: 6-8 Stunden
• Methode: Code-Trace von Resolver → Data-Layer (aus Code-Evidence-Agent)
• Deliverable: Alle data_layer_module: null → korrekte Module

---

P2 (NEXT SPRINT - MEDIUM PRIORITY)

7. Ungenutzte Platzhalter - Integration planen (67)

• Aufwand: 4-6 Stunden
• Methode:
  • Produktmanagement-Review: Timeline für 30 geplante Platzhalter (Phase 0c/1/2)
  • Technische Review: Prompt-Use-Cases für 37 plausible Platzhalter
• Deliverable: Integration-Roadmap, Prompt-Templates (5-10 Quick Wins)

8. Metadata-Completeness-Score auf >60% (111)

• Aufwand: 10-12 Stunden
• Methode: Systematisches Füllen aller Pflichtfelder
• Target: Mindestens 60% der Platzhalter mit Score >60

9. Schema-Status auf production (20-30 Core-Platzhalter)

• Aufwand: 4-6 Stunden
• Kriterien:
  • Metadata-Completeness >= 80%
  • Used-By >= 1
  • Keine Known-Issues
  • Zeitfenster + Confidence definiert
• Deliverable: 20-30 produktionsreife Platzhalter

---

P3 (LATER - NICE TO HAVE)

10. Validation-Framework für neue Platzhalter

• Aufwand: 16-20 Stunden
• Features:
  • Pre-Commit-Hook: Validierung gegen Normative Spec
  • CI/CD: Automatische Konsistenz-Checks (Code ↔ Catalog)
  • Template-Generator für neue Platzhalter

11. Migration-Guides für Prompt-Bibliothek

• Aufwand: 8-12 Stunden
• Content:
  • Best-Practice-Guide (basierend auf nutrition_avg)
  • Anti-Patterns (was vermeiden)
  • Upgrade-Path für Legacy-Prompts

---

Geschätzter Gesamt-Remediationsaufwand

Priority	Aufwand	Timeline	Dependencies
P0	14-20h	Week 1	Keine (sofort startbar)
P1	26-34h	Week 2-3	Nach P0
P2	18-24h	Week 4-5	Nach P1
P3	24-32h	Later	Nach P2
TOTAL	82-110h	4-6 Wochen	Gestaffelt

Mit Team von 2 Entwicklern: 2-3 Wochen für P0+P1, weitere 1-2 Wochen für P2.

---

Abschluss-Statement

Der Placeholder-Audit hat massive systemische Gaps identifiziert, aber auch einen klaren Remediation-Pfad aufgezeigt. Die größten Probleme sind:

1. Dokumentations-Gaps (44% ohne Kategorie/Beschreibung)
2. Zeitfenster-Chaos (67% ohne definiertes Fenster)
3. Fehlende Confidence-Systeme (93% ohne Qualitäts-Signale)

Die gute Nachricht: Alle 111 Platzhalter sind im Code implementiert, haben eine saubere Architektur, und 8 dienen bereits als Best-Practice-Modelle. Die Lücken sind primär dokumentarisch und metadatenbezogen, nicht funktional.

Mit einem strukturierten P0-P3-Plan (82-110h Aufwand) kann das System in 4-6 Wochen auf >60% Normkonformität gebracht werden.

Empfohlene nächste Schritte:

1. Review dieses Executive Summary mit Product/Tech Lead
2. P0-Priorisierung bestätigen (Zeitfenster, Code-Docs-Konflikte, Kategorien)
3. Kickoff für P0-Sprint (Ziel: 74 Zeitfenster + 49 Kategorien/Beschreibungen)

---

Audit durchgeführt von: Claude Code (Lead Audit Agent) Agent-Team: Code-Evidence, Semantic-Contract, Time-Window-Confidence, Prompt-Usage Normative Basis: PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md v1.0.0 Vollständige Artefakte: Siehe audit-report-2026-03-29/ für Gap-Cluster, Maßnahmenplan, Prüfmatrix