docs: Struktur .claude/docs versionieren, working/, Gitea-Index, Regeln

- .gitignore: .claude/docs, rules, commands tracken; settings.local weiter ignorieren
- DOCUMENTATION.md: verbindliche Ablage functional/technical/working/issues
- .claude/README.md: Agent-Einstieg; GITEA_ISSUES_INDEX aus MCP (Stand 2026-04-08)
- Arbeitspapiere von docs/ nach .claude/docs/working/ verschoben
- docs/MEMBERSHIP_SYSTEM.md als Stub; kanonisch technical/MEMBERSHIP_SYSTEM.md
- CLAUDE.md Pflichtlektüre und Links angepasst; docs/README.md vereinfacht

Made-with: Cursor
This commit is contained in:
Lars committed 2026-04-08 13:01:49 +02:00
1 parent 24daeeb83c
commit 7940dc7560
115 files changed
+45622 -1063

No files matched your search

@@ -0,0 +1,186 @@
# Code-Audit Mitai Jinkendo
| Feld | Wert |
|------|------|
| **Datum** | 2026-04-04 |
| **Bezeichnung** | Vollständige Code-Analyse (Backend FastAPI, Frontend React, Konfiguration) |
| **Umfang** | Stichproben + gezielte Suche (Security-Patterns, Auth, SQL, Hardcoding, Duplikate) |
| **Einschränkung** | Kein Penetrationstest, keine Laufzeit-Fuzzing-Tests; statische Analyse und Architektur-Review |
---
## Kurzfassung
Die Codebasis ist insgesamt strukturiert (modulare Router, parametrisierte SQL-Queries, bcrypt, Rate-Limits auf sensiblen Auth-Endpunkten). Es gibt jedoch **kritische Autorisierungslücken** rund um `X-Profile-Id` und die öffentlichen `/api/profiles`-Routen sowie eine **fehlende Objekt-Zuordnung bei Foto-Downloads**. Zusätzlich fallen **Konfigurations- und Versions-Inkonsistenzen**, **Legacy-/Duplikat-Code** und **Abweichungen von den eigenen Coding Rules** (direktes `fetch` im Frontend) auf.
**Gitea-Issue-Vorlagen** für die wichtigsten Punkte liegen unter `gitea/`.
---
## Kritisch (P0) – Sicherheit
### 1. `X-Profile-Id` ohne Abgleich mit der Session (`get_pid`)
**Datei:** `backend/routers/profiles.py` (Hilfsfunktion `get_pid`)
```20:29:backend/routers/profiles.py
def get_pid(x_profile_id: Optional[str] = Header(default=None)) -> str:
"""Get profile_id - from header for legacy endpoints."""
if x_profile_id:
return x_profile_id
with get_db() as conn:
cur = get_cursor(conn)
cur.execute("SELECT id FROM profiles ORDER BY created LIMIT 1")
row = cur.fetchone()
if row: return row['id']
raise HTTPException(400, "Kein Profil gefunden")
```
Ist der Header gesetzt, wird **jede** authentifizierte Session auf die **beliebig gewählte** Profil-ID umgebogen. `get_pid` wird in zahlreichen Routern genutzt (Gewicht, Aktivität, Ernährung, Fotos-Upload/Liste, Vitals, Insights, …). Ein Angreifer mit gültigem Nutzer-Token kann damit **fremde Daten lesen und schreiben** (klassische IDOR-Schwachstelle).
**Empfehlung:** Profil-Kontext ausschließlich aus `session['profile_id']` ableiten; `X-Profile-Id` nur für **Admins** erlauben und gegen eine explizite Admin-Prüfung validieren – oder entfernen, wenn nicht mehr benötigt.
**Vorlage:** `gitea/TEMPLATE_P0-profile-scoping-x-profile-id.md`
---
### 2. `/api/profiles`-Endpunkte ohne Admin-Pflicht
**Datei:** `backend/routers/profiles.py`
Endpunkte wie `GET/POST /api/profiles`, `GET/PUT/DELETE /api/profiles/{pid}` nutzen `Depends(require_auth)`, **nicht** `require_admin`. Damit kann jeder eingeloggte Nutzer u. a. **alle Profile auflisten**, **Profildaten abrufen** und unter Umständen **Profile löschen** (wenn mehr als eines existiert).
Das Frontend nutzt `GET /api/profiles` in `ProfileContext.jsx` für die Profilliste – funktional erklärbar, **sicherheitstechnisch** aber nur akzeptabel, wenn ausschließlich Admins je Instanz ein Konto haben (Annahme, die im Code nicht erzwungen wird).
**Empfehlung:** Öffentliche/„current user“-API von Admin-CRUD trennen; Listen/Löschen/Anlegen fremder Profile nur mit `require_admin` und expliziter Policy.
**Vorlage:** `gitea/TEMPLATE_P0-profiles-router-authorization.md`
---
### 3. Foto-Abruf ohne Profil-Ownership-Prüfung
**Datei:** `backend/routers/photos.py` – `GET /api/photos/{fid}`
Die Route lädt die Datei nur anhand der Foto-`id`, **ohne** zu prüfen, ob `photos.profile_id` zur Session passt. UUIDs erschweren Raten, bieten aber **keinen** Zugriffsschutz, wenn IDs bekannt sind oder geleakt werden.
**Empfehlung:** `SELECT ... WHERE id=%s AND profile_id=%s` mit `session['profile_id']` (bzw. adminseitig explizite Ausnahme).
**Vorlage:** `gitea/TEMPLATE_P1-photo-ownership-enforcement.md`
---
## Hoch (P1)
### 4. CORS: Default `allow_origins=["*"]`
**Datei:** `backend/main.py`
Wenn `ALLOWED_ORIGINS` nicht gesetzt ist, erlaubt die Middleware **`'*'`** in Kombination mit `allow_credentials=True`. Das ist in Browsern problematisch (kann je nach Client zu unerwartetem Verhalten führen) und in Produktion **riskant**, falls die Umgebungsvariable fehlt.
**Empfehlung:** In Produktion kein Wildcard-Default; Startfehler oder restriktive Default-Liste für Dev dokumentieren.
**Vorlage:** `gitea/TEMPLATE_P1-cors-allowed-origins-hardening.md`
---
### 5. Session-Token in der URL (Fotos)
**Datei:** `frontend/src/utils/api.js` – Foto-URL mit `?token=...` für `<img>`-Tags; Backend: `require_auth_flexible` mit Query-Parameter.
Token in URLs landen in **Logs, Referer, Browser-Historie** – erhöhtes Leak-Risiko.
**Empfehlung:** Kurzlebige signierte URLs, Cookie-Session für Same-Origin, oder dedizierter Download-Endpoint mit Header-Auth und Blob-URL im Frontend (mit Aufwand abzuwägen).
---
### 6. Veraltete / widersprüchliche Versionsangaben
| Ort | Befund |
|-----|--------|
| `backend/main.py` | `FastAPI(..., version="3.0.0")` – wirkt wie API-/Framework-Version, nicht App-Version |
| `backend/version.py` | `APP_VERSION = "0.9l"` |
| `backend/routers/auth.py` `/api/auth/status` | `"version": "v9b"` – offensichtlich veraltet |
| `CLAUDE.md` | erwähnt `frontend/src/version.js` – **Datei im Repo nicht vorhanden** (Dokumentationsdrift) |
**Empfehlung:** Eine Quelle (`version.py` + optional Endpoint `/api/version`), Frontend aus derselben Quelle oder Build-Inject.
---
## Mittel (P2) – Inkonsistenzen & Wartung
### 7. Frontend: direktes `fetch` statt `api.js`
Laut `.claude/rules/CODING_RULES.md` sollen alle API-Calls über `api.js` laufen. Tatsächlich gibt es u. a.:
- `frontend/src/context/AuthContext.jsx`, `ProfileContext.jsx`, `PasswordRecovery.jsx`
- `frontend/src/pages/AdminPanel.jsx`, `SettingsPage.jsx`
Risiko: inkonsistente Header/Fehlerbehandlung, schwerer zu auditieren.
**Vorlage:** `gitea/TEMPLATE_P2-consolidate-api-client.md`
---
### 8. Duplikat- und Legacy-Code
| Befund | Hinweis |
|--------|---------|
| `backend/main_old.py` | Großes, nicht eingebundenes Modul – verwirrt Reviews und Suche |
| `backend/calculations/*` vs `backend/data_layer/*` | Parallelstruktur; Phase-0c nutzt `data_layer`, aber z. B. `placeholder_resolver.py` importiert noch `calculations.scores` |
| `backend/apply_v9c_migration.py` in `startup_event` | Legacy-Hook neben `db_init` – technische Schuld |
**Vorlage:** `gitea/TEMPLATE_P2-dead-code-and-metrics-dedup.md`
---
### 9. Hardcodierte Werte (Auswahl)
- **Tests:** `tests/dev-smoke-test.spec.js` – Fallback-Passwort `'5112'` wenn `TEST_PASSWORD` fehlt (nur für lokale/CI-Umgebung akzeptabel, sollte in Doku stehen und nie in Prod-Daten).
- **Playwright:** `playwright.config.js` – feste `baseURL: 'https://dev.mitai.jinkendo.de'`.
- **Admin-UI:** `AdminPanel.jsx` – Beispielzeile mit `APP_URL=http://192.168.2.49:3002` (Dokumentation im UI).
- **Farben:** Viele Hex-Werte in JSX (z. B. `NutritionCharts.jsx`, `History.jsx`) – Verstoß gegen die eigene CSS-Variablen-Regel, aber eher UX/Wartbarkeit als Security.
### 10. Passwortlänge: `/api/auth/pin` vs Registrierung
Registrierung verlangt mindestens **8** Zeichen; PIN-/Passwort-Änderung über `/api/auth/pin` erlaubt **4** Zeichen. Inkonsistent für Sicherheitskommunikation.
### 11. Dynamische SQL-`UPDATE`-Fragmente
Muster `UPDATE ... SET {', '.join(f'{k}=%s' for k in d)}` erscheint in mehreren Routern. **Soweit geprüft**, werden Keys aus kontrollierten Dicts/Pydantic-Modellen gebaut – **kein** offensichtlicher SQL-Injection-Pfad durch Rohtext. Risiko steigt, wenn später unkontrollierte Keys eingespeist werden. Whitelist pro Endpoint wäre robuster.
---
## Positiv hervorgehoben
- Parametrisierte Queries (`%s`) durchgängig üblich; keine `execute(f"...{userinput}")` in den geprüften kritischen Pfaden.
- `bcrypt` + Migration von Legacy-SHA256 in `auth.py` / Login.
- Rate Limiting auf Login, Forgot-Password, Register (`slowapi`).
- Forgot-Password gibt keine E-Mail-Existenz preis.
- Admin-Router (`/api/admin/*`) konsequent mit `require_admin`.
- Modulare Router-Registrierung in `main.py`.
---
## Mapping: Vorlagen → Themen
| Priorität | Thema | Datei unter `gitea/` |
|-----------|--------|----------------------|
| P0 | IDOR `X-Profile-Id` / `get_pid` | `TEMPLATE_P0-profile-scoping-x-profile-id.md` |
| P0 | `/api/profiles` ohne Admin | `TEMPLATE_P0-profiles-router-authorization.md` |
| P1 | Foto-Ownership | `TEMPLATE_P1-photo-ownership-enforcement.md` |
| P1 | CORS-Default | `TEMPLATE_P1-cors-allowed-origins-hardening.md` |
| P2 | `fetch` vs `api.js` | `TEMPLATE_P2-consolidate-api-client.md` |
| P2 | Legacy/Duplikate | `TEMPLATE_P2-dead-code-and-metrics-dedup.md` |
---
## Nächste Schritte (empfohlen)
1. **Sofort:** P0-Issues planen und `get_pid` / Profil-Router designen (Session-first, Admin-Override explizit).
2. **Kurzfristig:** Foto-GET mit `profile_id`-Check; CORS in allen Umgebungen prüfen.
3. **Mittelfristig:** Versionierung vereinheitlichen; `fetch`-Calls bündeln; `main_old.py` und Metrik-Duplikate bereinigen oder archivieren.
---
*Erstellt im Rahmen einer statischen Code-Analyse; bei Änderungen am Code bitte Report-Datum und Befunde aktualisieren.*
@@ -0,0 +1,8 @@
# Audit 2026-04-04 – Code Review
| Inhalt | Pfad |
|--------|------|
| Vollständiger Report | [`CODE_AUDIT_REPORT_2026-04-04.md`](./CODE_AUDIT_REPORT_2026-04-04.md) |
| Gitea-Issue-Vorlagen (Copy & Paste) | [`gitea/`](./gitea/) |
Beim Anlegen in Gitea: **Titel** und **Labels** aus dem YAML-Kopf der jeweiligen Vorlage übernehmen, **Beschreibung** = Rest des Markdown (ohne die `---`-Blöcke, falls gewünscht).
@@ -0,0 +1,37 @@
---
# Gitea: Beim Anlegen des Issues Titel und Labels manuell übernehmen (YAML wird von Gitea nicht automatisch geparst – dient als Meta-Hinweis).
title: "[Security/P0] X-Profile-Id / get_pid ermöglicht IDOR über alle Datendomänen"
labels: security, backend, priority-critical
---
## Kontext
Code-Audit 2026-04-04 (`/.claude/docs/audit/20260404_code_audit/CODE_AUDIT_REPORT_2026-04-04.md`).
## Problem
Die Funktion `get_pid` in `backend/routers/profiles.py` gibt bei gesetztem Header `X-Profile-Id` diesen Wert **unverändert** zurück, **ohne** Abgleich mit `session['profile_id']` oder Admin-Rolle.
Damit kann jede authentifizierte Session mit gültigem Token Daten eines **beliebigen** Profils über alle Endpunkte ansprechen, die `get_pid(x_profile_id)` nutzen (u. a. Gewicht, Aktivität, Ernährung, Fotos-Upload/Liste, Vitals, Insights, Schlaf, Ruhetage, Export).
## Reproduktion (konzeptionell)
1. Als Nutzer A einloggen, Token erhalten.
2. Profil-ID von Nutzer B ermitteln (z. B. über `GET /api/profiles` – siehe separates Issue).
3. Request gegen geschützten Endpoint mit Header `X-Profile-Id: <uuid-von-B>` und Token von A.
## Erwartetes Verhalten
- Standard: `profile_id` **ausschließlich** aus der Session.
- Optional: `X-Profile-Id` nur für **Admins** und mit expliziter Prüfung `require_admin` + dokumentierter Use-Case (Multi-User-Admin-UI).
## Akzeptanzkriterien
- [ ] Alle betroffenen Router verwenden session-basierte Profil-IDs oder einen validierten Admin-Override.
- [ ] Regressionstests oder manuelle Checkliste für mindestens einen Endpoint pro Router-Gruppe.
- [ ] Kurze Doku in `.claude/rules` oder technischer Doc, ob `X-Profile-Id` noch existiert und wann.
## Betroffene Dateien (Ausgangspunkt)
- `backend/routers/profiles.py` (`get_pid`)
- Alle Importe von `get_pid` (z. B. `weight`, `activity`, `nutrition`, `photos`, `insights`, `vitals_baseline`, `blood_pressure`, `rest_days`, `sleep`, …)
@@ -0,0 +1,37 @@
---
title: "[Security/P0] /api/profiles CRUD ohne require_admin – Datenabfluss und Missbrauch"
labels: security, backend, priority-critical
---
## Kontext
Code-Audit 2026-04-04.
## Problem
In `backend/routers/profiles.py` nutzen u. a. folgende Routen `Depends(require_auth)` **ohne** `require_admin`:
- `GET /api/profiles` – Liste aller Profile
- `POST /api/profiles` – Profil anlegen
- `GET/PUT/DELETE /api/profiles/{pid}` – Abruf/Update/Löschen nach ID
Jeder eingeloggte Nutzer kann damit die Profilliste sehen und je nach Datenbestand auch fremde Profile manipulieren oder löschen (sofern mehr als ein Profil existiert).
Das Frontend (`ProfileContext.jsx`) ruft `GET /api/profiles` für die Profilauswahl auf – das erklärt die aktuelle UX, ersetzt aber keine serverseitige Autorisierung.
## Erwartetes Verhalten
- Listen, Anlegen, Löschen und Bearbeiten **fremder** Profile: nur `require_admin`.
- „Aktuelles Profil“: dedizierte Routen (`/api/profile` o. ä.) strikt an `session['profile_id']` gebunden.
## Akzeptanzkriterien
- [ ] Rollenmodell dokumentiert (wer darf `/api/profiles` sehen?).
- [ ] Admin-only für sensible Operationen erzwungen.
- [ ] Frontend angepasst (falls nötig: Admin vs. normaler Nutzer unterschiedliche Endpunkte).
- [ ] Keine Regression für Single-User-Selfhosting ohne unnötige UX-Brüche (optional: Feature-Flag oder Rolle `admin` für ersten User).
## Betroffene Dateien
- `backend/routers/profiles.py`
- `frontend/src/context/ProfileContext.jsx` (und ggf. weitere Aufrufer von `/api/profiles`)
@@ -0,0 +1,36 @@
---
title: "[Security/P1] CORS: Default ALLOWED_ORIGINS=* mit allow_credentials=True"
labels: security, backend, configuration, priority-high
---
## Kontext
Code-Audit 2026-04-04.
## Problem
`backend/main.py`:
```python
allow_origins=os.getenv("ALLOWED_ORIGINS", "*").split(","),
allow_credentials=True,
```
Fehlt die Umgebungsvariable, ist die Default-Konfiguration `*`. Zusammen mit `allow_credentials=True` ist das in Produktion unerwünscht und erschwert eine klare Security-Posture.
## Erwartetes Verhalten
- Produktion: explizite Origins aus `ALLOWED_ORIGINS` (kommasepariert), kein stiller Wildcard-Fallback.
- Entwicklung: dokumentierter Default (z. B. `http://localhost:5173`) oder explizite Opt-in-Umgebungsvariable `CORS_ALLOW_ALL=true`.
## Akzeptanzkriterien
- [ ] Verhalten in `.env.example` und Deployment-Doku beschrieben.
- [ ] Optional: Anwendung startet nicht, wenn `ALLOWED_ORIGINS` in `ENV=production` fehlt.
- [ ] Manuelle Prüfung: Browser-Requests von fremden Origins werden blockiert.
## Betroffene Dateien
- `backend/main.py`
- `.env.example`
- ggf. `docker-compose*.yml`
@@ -0,0 +1,36 @@
---
title: "[Security/P1] GET /api/photos/{fid} ohne Prüfung auf profile_id (Objekt-Zugriff)"
labels: security, backend, priority-high
---
## Kontext
Code-Audit 2026-04-04.
## Problem
`backend/routers/photos.py`: `GET /{fid}` lädt ein Foto nur anhand der `id` aus der Tabelle `photos`, ohne zu prüfen, ob der Datensatz zu `session['profile_id']` gehört.
Authentifizierung ist vorhanden (`require_auth_flexible`), aber **keine Objekt-Level-Autorisierung**.
## Risiko
Bei bekannter oder erratener Foto-UUID können Inhalte anderer Nutzer derselben Instanz abgerufen werden.
## Erwartetes Verhalten
```sql
SELECT path FROM photos WHERE id = %s AND profile_id = %s
```
mit `profile_id` aus der Session; Admins optional mit separatem Codepfad.
## Akzeptanzkriterien
- [ ] Abruf nur für eigenes Profil (bzw. dokumentierter Admin-Fall).
- [ ] Bestehende Clients (PWA) unverändert nutzbar.
- [ ] Kurzer Testfall oder manuelle Prüfung: Nutzer A kann Foto von B nicht öffnen.
## Betroffene Dateien
- `backend/routers/photos.py`
@@ -0,0 +1,30 @@
---
title: "[Tech-Debt/P2] Frontend: direktes fetch statt zentral api.js (Auth, Admin, Import)"
labels: frontend, refactoring, consistency
---
## Kontext
Code-Audit 2026-04-04. Verbindliche Regel: `.claude/rules/CODING_RULES.md` – alle API-Calls über `frontend/src/utils/api.js`.
## Problem
Mehrere Komponenten nutzen natives `fetch('/api/...')` mit manuell gesetztem `X-Auth-Token`, u. a.:
- `frontend/src/context/AuthContext.jsx`
- `frontend/src/context/ProfileContext.jsx`
- `frontend/src/pages/PasswordRecovery.jsx`
- `frontend/src/pages/AdminPanel.jsx`
- `frontend/src/pages/SettingsPage.jsx`
Nachteile: doppelte Fehlerbehandlung, schwerere Wartung, leichter zu übersehen bei Security-Reviews.
## Erwartetes Verhalten
Alle Aufrufe über `api.js` (oder ein einziges dünnes Wrapper-Modul), inkl. Upload/Export-Sonderfälle.
## Akzeptanzkriterien
- [ ] Kein direktes `fetch('/api/` mehr außerhalb von `api.js` (Ausnahmen dokumentieren, falls nötig).
- [ ] Einheitliche Fehler- und 401-Behandlung.
- [ ] Kurze Notiz in CODING_RULES oder LESSONS_LEARNED, falls Ausnahmen bleiben.
@@ -0,0 +1,34 @@
---
title: "[Tech-Debt/P2] Legacy main_old.py, calculations/ vs data_layer/, Startup-Migration-Hooks"
labels: backend, refactoring, maintenance
---
## Kontext
Code-Audit 2026-04-04.
## Problemstellung (Bündel)
1. **`backend/main_old.py`**: große, nicht in `main.py` eingebundene Datei – verwirrt Suche, Reviews und Onboarding.
2. **Parallele Metrik-Pfade**: `backend/data_layer/` (Phase 0c) und `backend/calculations/` existieren nebeneinander; `placeholder_resolver.py` importiert z. B. noch `calculations.scores`.
3. **`startup_event` in `main.py`**: zusätzlicher Hook `apply_v9c_migration` neben `db_init` – Legacy-Pfad neben dem Migrations-System.
## Ziele
- Single Source of Truth für Metriken (klar dokumentiert: `data_layer` vs. verbleibende Hilfsmodule).
- Entfernen oder Archivieren (`docs/archive/` oder Git-History-only) von `main_old.py`, sofern nicht mehr referenziert.
4. Migration-Startup vereinheitlichen (nur `db_init` / nummerierte SQL-Migrationen, sofern v9c-Hook obsolet).
## Akzeptanzkriterien
- [ ] Entscheidung dokumentiert: welches Paket autoritativ ist.
- [ ] Keine doppelten Implementierungen für dieselbe Metrik ohne Grund.
- [ ] `main_old.py` entfernt oder klar als „archived“ markiert und aus IDEs/CI-Suche ausgeschlossen (optional).
- [ ] Build/Start ohne v9c-Sonderpfad, falls redundant.
## Betroffene Pfade (Start)
- `backend/main_old.py`
- `backend/main.py` (startup)
- `backend/data_layer/`, `backend/calculations/`
- `backend/placeholder_resolver.py`
+10
View File
@@ -0,0 +1,10 @@
# Audit- und Reconcile-Artefakte
Zeitlich begrenzte Reviews, Matrizen und Gitea-Vorlagen. **Keine** verbindlichen Produkt-Spezifikationen – die bleiben unter [`functional/`](../functional/) und [`technical/`](../technical/).
| Ordner | Inhalt |
|--------|--------|
| [`20260404_code_audit/`](./20260404_code_audit/) | Code-Audit 2026-04-04, Report + Issue-Vorlagen |
| [`platzhalter/`](./platzhalter/) | Platzhalter-Audits, Kataloge, Reconciliation 2026-03 (JSON/Matrix) |
**Hinweis:** Doppelablagen zu `functional/` wurden entfernt (z. B. fachliche `DATA_ARCHITECTURE`, Konzept-PDF-Markdown v2). Immer die Pfade unter `functional/` bzw. `technical/` als Quelle nutzen.
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,147 @@
# Placeholder Catalog (Extended)
**Generated:** 2026-03-29 19:26:40
**Total Placeholders:** 111
## Placeholders by Category
### Ernährung (8 placeholders)
- `{{carb_avg}}` - Durchschn. Kohlenhydrate in g (30d)
- `{{energy_balance_7d}}` - Energiebilanz 7d (kcal/Tag)
- `{{fat_avg}}` - Durchschn. Fett in g (30d)
- `{{kcal_avg}}` - Durchschn. Kalorien (30d)
- `{{macro_consistency_score}}` - Makro-Konsistenz Score (0-100)
- `{{protein_adequacy_28d}}` - Protein Adequacy Score (0-100)
- `{{protein_avg}}` - Durchschn. Protein in g (30d)
- `{{protein_g_per_kg}}` - Protein g/kg Körpergewicht
### Focus Areas (8 placeholders)
- `{{focus_cat_aktivität_progress}}` - Kategorie Aktivität - Progress (%)
- `{{focus_cat_aktivität_weight}}` - Kategorie Aktivität - Gewichtung (%)
- `{{focus_cat_ernährung_progress}}` - Kategorie Ernährung - Progress (%)
- `{{focus_cat_ernährung_weight}}` - Kategorie Ernährung - Gewichtung (%)
- `{{focus_cat_körper_progress}}` - Kategorie Körper - Progress (%)
- `{{focus_cat_körper_weight}}` - Kategorie Körper - Gewichtung (%)
- `{{top_focus_area_name}}` - Top Focus Area Name
- `{{top_focus_area_progress}}` - Top Focus Area Progress (%)
### Körper (11 placeholders)
- `{{bmi}}` - Body Mass Index
- `{{fm_28d_change}}` - Fettmasse Änderung 28d (kg)
- `{{kf_aktuell}}` - Aktueller Körperfettanteil in %
- `{{lbm_28d_change}}` - Magermasse Änderung 28d (kg)
- `{{recomposition_quadrant}}` - Rekomposition-Status
- `{{waist_28d_delta}}` - Taillenumfang Änderung 28d (cm)
- `{{waist_hip_ratio}}` - Taille/Hüfte-Verhältnis
- `{{weight_28d_slope}}` - Gewichtstrend 28d (kg/Tag)
- `{{weight_7d_median}}` - Gewicht 7d Median (kg)
- `{{weight_aktuell}}` - Aktuelles Gewicht in kg
- `{{weight_trend}}` - Gewichtstrend (7d/30d)
### Profil (4 placeholders)
- `{{age}}` - Alter in Jahren
- `{{geschlecht}}` - Geschlecht
- `{{height}}` - Körpergröße in cm
- `{{name}}` - Name des Nutzers
### Schlaf & Erholung (7 placeholders)
- `{{rest_days_count}}` - Anzahl Ruhetage (30d)
- `{{sleep_avg_duration}}` - Durchschn. Schlafdauer (7d)
- `{{sleep_avg_duration_7d}}` - Schlaf 7d (Stunden)
- `{{sleep_avg_quality}}` - Durchschn. Schlafqualität (7d)
- `{{sleep_debt_hours}}` - Schlafschuld (Stunden)
- `{{sleep_quality_7d}}` - Schlafqualität 7d (0-100)
- `{{sleep_regularity_proxy}}` - Schlaf-Regelmäßigkeit (Min Abweichung)
### Scores (Phase 0b) (6 placeholders)
- `{{activity_score}}` - Activity Score (0-100)
- `{{body_progress_score}}` - Body Progress Score (0-100)
- `{{data_quality_score}}` - Data Quality Score (0-100)
- `{{goal_progress_score}}` - Goal Progress Score (0-100)
- `{{nutrition_score}}` - Nutrition Score (0-100)
- `{{recovery_score}}` - Recovery Score (0-100)
### Training (9 placeholders)
- `{{ability_balance_endurance}}` - Ability Balance - Ausdauer (0-100)
- `{{ability_balance_strength}}` - Ability Balance - Kraft (0-100)
- `{{activity_summary}}` - Aktivitäts-Zusammenfassung (7d)
- `{{proxy_internal_load_7d}}` - Proxy Load 7d
- `{{quality_sessions_pct}}` - Qualitätssessions (%)
- `{{rest_day_compliance}}` - Ruhetags-Compliance (%)
- `{{training_frequency_7d}}` - Trainingshäufigkeit 7d
- `{{training_minutes_week}}` - Trainingsminuten pro Woche
- `{{trainingstyp_verteilung}}` - Verteilung nach Trainingstypen
### Unknown (49 placeholders)
- `{{ability_balance_coordination}}` - No description available
- `{{ability_balance_mental}}` - No description available
- `{{ability_balance_mobility}}` - No description available
- `{{active_goals_json}}` - No description available
- `{{active_goals_md}}` - No description available
- `{{activity_detail}}` - No description available
- `{{arm_28d_delta}}` - No description available
- `{{caliper_summary}}` - No description available
- `{{chest_28d_delta}}` - No description available
- `{{circ_summary}}` - No description available
- `{{correlation_energy_weight_lag}}` - No description available
- `{{correlation_load_hrv}}` - No description available
- `{{correlation_load_rhr}}` - No description available
- `{{correlation_protein_lbm}}` - No description available
- `{{correlation_sleep_recovery}}` - No description available
- `{{energy_deficit_surplus}}` - No description available
- `{{focus_area_weights_json}}` - No description available
- `{{focus_areas_weighted_json}}` - No description available
- `{{focus_areas_weighted_md}}` - No description available
- `{{focus_cat_lebensstil_progress}}` - No description available
- `{{focus_cat_lebensstil_weight}}` - No description available
- `{{focus_cat_mental_progress}}` - No description available
- `{{focus_cat_mental_weight}}` - No description available
- `{{focus_cat_recovery_progress}}` - No description available
- `{{focus_cat_recovery_weight}}` - No description available
- `{{focus_cat_vitalwerte_progress}}` - No description available
- `{{focus_cat_vitalwerte_weight}}` - No description available
- `{{goal_bf_pct}}` - No description available
- `{{goal_weight}}` - No description available
- `{{hip_28d_delta}}` - No description available
- `{{intake_volatility}}` - No description available
- `{{monotony_score}}` - No description available
- `{{nutrition_days}}` - No description available
- `{{plateau_detected}}` - No description available
- `{{protein_days_in_target}}` - No description available
- `{{protein_ziel_high}}` - No description available
- `{{protein_ziel_low}}` - No description available
- `{{recent_load_balance_3d}}` - No description available
- `{{strain_score}}` - No description available
- `{{thigh_28d_delta}}` - No description available
- `{{top_3_focus_areas}}` - No description available
- `{{top_3_goals_behind_schedule}}` - No description available
- `{{top_3_goals_on_track}}` - No description available
- `{{top_drivers}}` - No description available
- `{{top_goal_name}}` - No description available
- `{{top_goal_progress_pct}}` - No description available
- `{{top_goal_status}}` - No description available
- `{{weight_90d_slope}}` - No description available
- `{{zeitraum_90d}}` - No description available
### Vitalwerte (6 placeholders)
- `{{hrv_vs_baseline_pct}}` - HRV vs. Baseline (%)
- `{{rhr_vs_baseline_pct}}` - RHR vs. Baseline (%)
- `{{vitals_avg_hr}}` - Durchschn. Ruhepuls (7d)
- `{{vitals_avg_hrv}}` - Durchschn. HRV (7d)
- `{{vitals_vo2_max}}` - Aktueller VO2 Max
- `{{vo2max_trend_28d}}` - VO2max Trend 28d
### Zeitraum (3 placeholders)
- `{{datum_heute}}` - Heutiges Datum
- `{{zeitraum_30d}}` - 30-Tage-Zeitraum
- `{{zeitraum_7d}}` - 7-Tage-Zeitraum
@@ -0,0 +1,24 @@
# Placeholder Export Specification
**Version:** 1.0.0
**Generated:** 2026-03-29 19:26:40
## API Endpoints
### Extended Export
```
GET /api/prompts/placeholders/export-values-extended
Header: X-Auth-Token: <token>
```
Returns complete metadata for all 116 placeholders.
### ZIP Export (Admin)
```
GET /api/prompts/placeholders/export-catalog-zip
Header: X-Auth-Token: <token>
```
Returns ZIP with all catalog files.
@@ -0,0 +1,66 @@
# Placeholder Metadata Gap Report
**Generated:** 2026-03-29 19:26:40
**Total Placeholders:** 111
## Gaps Summary
### Missing Data Layer Module
Count: 100
- {{name}}
- {{age}}
- {{height}}
- {{geschlecht}}
- {{bmi}}
- {{goal_weight}}
- {{goal_bf_pct}}
- {{nutrition_days}}
- {{protein_ziel_low}}
- {{protein_ziel_high}}
- ... and 90 more
### Missing Semantic Contract
Count: 25
- {{bmi}}
- {{goal_bf_pct}}
- {{rest_days_count}}
- {{vitals_vo2_max}}
- {{data_quality_score}}
- {{top_goal_progress_pct}}
- {{waist_hip_ratio}}
- {{energy_deficit_surplus}}
- {{protein_days_in_target}}
- {{macro_consistency_score}}
- ... and 15 more
### Missing Source Tables
Count: 90
- {{name}}
- {{age}}
- {{height}}
- {{geschlecht}}
- {{bmi}}
- {{goal_weight}}
- {{goal_bf_pct}}
- {{nutrition_days}}
- {{protein_ziel_low}}
- {{protein_ziel_high}}
- ... and 80 more
### Unknown Time Window
Count: 74
- {{bmi}}
- {{caliper_summary}}
- {{goal_weight}}
- {{goal_bf_pct}}
- {{nutrition_days}}
- {{protein_ziel_low}}
- {{protein_ziel_high}}
- {{activity_summary}}
- {{activity_detail}}
- {{trainingstyp_verteilung}}
- ... and 64 more
@@ -0,0 +1,386 @@
# 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.
+5
View File
@@ -0,0 +1,5 @@
# Platzhalter-Audits (Archiv)
Enthält Kataloge, Gap-Reports und Reconciliation-Artefakte (2026-03). **Normative Entwicklerregeln** für Platzhalter: `../../technical/PLACEHOLDER_REGISTRY_FRAMEWORK.md`.
**Entfernte Doppelungen:** `DATA_ARCHITECTURE.md` und `mitai_jinkendo_konzept_diagramme_auswertungen_v2.md` lagen identisch auch hier – kanonisch sind jetzt nur noch `../../functional/DATA_ARCHITECTURE.md` bzw. `../../functional/mitai_jinkendo_konzept_diagramme_auswertungen_v2.md`.
@@ -0,0 +1,463 @@
# 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
@@ -0,0 +1,651 @@
# Gap-Cluster-Bericht: Placeholder-Audit
**Audit-Datum:** 29. März 2026
**Basis:** 111 Platzhalter, 4-Agent-Analyse
**Normative Referenz:** PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md v1.0.0
---
## Übersicht
Dieser Bericht gruppiert die identifizierten Gaps nach **systemischen Clustern**, um gezielte Remediation-Strategien zu ermöglichen.
**Gesamtzahl Gaps:** 481 einzelne Gap-Instanzen über alle 111 Platzhalter
**Gap-Verteilung:**
```
Non-Compliant (81): 324 Gaps (durchschnittlich 4.0 pro Placeholder)
Partially Compliant (22): 88 Gaps (durchschnittlich 4.0 pro Placeholder)
Compliant (8): 0 Gaps
```
---
## GAP-CLUSTER
### CLUSTER 1: Missing Semantic Contract
**Anzahl betroffene Platzhalter:** 49 (44%)
**Severity:** 🔴 CRITICAL
**Norm-Verstoß:** §7.1 Pflichtfelder (description, semantic_contract)
**Sub-Kategorien:**
#### 1.1 No Description Available (49)
Alle 49 haben `description: "No description available"`
**Betroffene Kategorien:**
- **Unknown (49):** Alle 49 Non-Compliant sind in "Unknown"-Kategorie
- Ability Balance (5): coordination, endurance, mental, mobility, strength
- Correlations (5): energy_weight_lag, load_hrv, load_rhr, protein_lbm, sleep_recovery
- Body Deltas (5): arm_28d_delta, chest_28d_delta, hip_28d_delta, thigh_28d_delta, waist_28d_delta (doppelt)
- Goals (16): active_goals_json/md, focus_areas, top_goal_*, top_3_goals_*, goal_weight, goal_bf_pct
- Nutrition (6): energy_deficit_surplus, intake_volatility, nutrition_days, protein_days_in_target, protein_ziel_*
- Training (3): activity_detail, monotony_score, strain_score
- Summaries (3): caliper_summary, circ_summary, weight_90d_slope
- Meta (2): zeitraum_90d, recent_load_balance_3d
- Plateau (1): plateau_detected
- Top Drivers (1): top_drivers
**Remediation:**
- **Bulk-Update möglich:** Semantic-Contract-Agent-Report hat Target-Descriptions für alle 49
- **Aufwand:** 4-6 Stunden (Copy-Paste aus Agent-Report)
- **Priority:** P0 (blocking für Production)
---
#### 1.2 Weak Semantic Contract (25)
Haben Beschreibung, aber schwachen/unvollständigen Semantic Contract
**Beispiele:**
- `bmi`: Description OK, aber Semantic Contract = Description (sollte Formel enthalten)
- `rest_days_count`: Description OK, aber Aggregationslogik fehlt
- `vitals_vo2_max`: Description OK, aber Quelle/Berechnungsmethode fehlt
**Remediation:**
- **Individuelle Überarbeitung:** Semantic Contract mit Formeln/Quellen/Aggregationen anreichern
- **Aufwand:** 3-4 Stunden
- **Priority:** P1
---
### CLUSTER 2: Missing Data Layer Module
**Anzahl betroffene Platzhalter:** 100 (90%)
**Severity:** 🔴 CRITICAL
**Norm-Verstoß:** §7 Source vollständig (data_layer_module erforderlich)
**Analyse:**
- Nur 11 Platzhalter haben `data_layer_module` gesetzt
- 100 haben `data_layer_module: null`
**Root Cause:**
- Export-System extrahiert `data_layer_module` nur, wenn explizit in Code-Kommentaren
- Resolver nutzen oft Helper-Funktionen (`_safe_int`, `_safe_float`) statt direkter Data-Layer-Calls
- `_safe_int` ruft intern Data-Layer auf, aber Mapping ist nicht dokumentiert
**Code-Evidence-Agent Findings:**
- **81 nutzen Helper** (`_safe_int`, `_safe_float`, `_safe_str`, `_safe_json`)
- Diese HABEN Data-Layer-Module, sind aber nicht dokumentiert
- Beispiel: `_safe_int('nutrition_score', pid)` → ruft `data_layer.nutrition_metrics.calculate_nutrition_score()`
- **19 haben direkte Data-Layer-Calls** (z.B. nutrition_avg, weight_aktuell)
- **0 echte Fälle ohne Data-Layer** (alle 111 haben technische Herkunft)
**Remediation:**
- **Code-Trace von Resolvern:** Für jede `_safe_*`-Funktion die gerufene Data-Layer-Funktion identifizieren
- **Bulk-Update:** Mapping aus Code-Evidence-Agent-Report übernehmen
- **Aufwand:** 6-8 Stunden
- **Priority:** P1
---
### CLUSTER 3: Missing Source Tables
**Anzahl betroffene Platzhalter:** 90 (81%)
**Severity:** 🔴 CRITICAL
**Norm-Verstoß:** §7 Source vollständig (source_tables erforderlich)
**Analyse:**
- Nur 21 Platzhalter haben `source_tables` gesetzt
- 90 haben `source_tables: []`
**Root Cause:**
- Identisch zu CLUSTER 2: Export-System extrahiert nicht aus Code
- Source-Tables sind in Data-Layer-SQL-Queries definiert, aber nicht in Resolver-Metadaten
**Code-Evidence-Agent Findings:**
- **Alle 111** haben identifizierbare Source-Tables im Code
- **9 Core-Tables:**
1. `profiles` (4 Platzhalter)
2. `weight_log` (11)
3. `nutrition_log` (12)
4. `activity_log` (14)
5. `sleep_log` (6)
6. `vitals_baseline` (8)
7. `circumference_log` (5)
8. `caliper_log` (5)
9. `goals`, `focus_areas`, `rest_days` (11)
**Remediation:**
- **Automatische Extraktion:** SQL-Query-Parsing in Data-Layer-Modulen
- **Bulk-Update:** Mapping aus Code-Evidence-Agent-Report übernehmen
- **Aufwand:** 6-8 Stunden
- **Priority:** P1
---
### CLUSTER 4: Unknown Time Window
**Anzahl betroffene Platzhalter:** 74 (67%)
**Severity:** 🔴 CRITICAL
**Norm-Verstoß:** §3.4 "Zeitfenster explizit"
**Analyse:**
- 74 haben `time_window: unknown`
- 37 haben definiertes Zeitfenster (latest, 7d, 28d, 30d, 90d, mixed)
**Sub-Kategorien:**
#### 4.1 Name enthält Zeitfenster, aber Metadaten unknown (15)
**KRITISCHER MISMATCH:**
| Placeholder | Name-Hint | Code | Metadaten | Fix |
|-------------|-----------|------|-----------|-----|
| `zeitraum_7d` | 7d | Hardcoded "letzte 7 Tage" | unknown | → 7d |
| `zeitraum_30d` | 30d | Hardcoded "letzte 30 Tage" | unknown | → 30d |
| `zeitraum_90d` | 90d | Hardcoded "letzte 90 Tage" | unknown | → 90d |
| `sleep_avg_duration_7d` | 7d | 7 days | unknown | → 7d |
| `sleep_quality_7d` | 7d | 7 days | unknown | → 7d |
| `training_frequency_7d` | 7d | 7 days (inferred) | unknown | → 7d |
| `proxy_internal_load_7d` | 7d | 7 days | unknown | → 7d |
| `energy_balance_7d` | 7d | 7 days | unknown | → 7d |
| `protein_adequacy_28d` | 28d | 28 days | unknown | → 28d |
| `weight_28d_slope` | 28d | 28 days | 28d | ✓ OK |
| `weight_90d_slope` | 90d | 90 days | 90d | ✓ OK |
| `fm_28d_change` | 28d | 28 days | 28d | ✓ OK |
| `lbm_28d_change` | 28d | 28 days | 28d | ✓ OK |
| `vo2max_trend_28d` | 28d | 28 days | 28d | ✓ OK |
| ... | | | | |
**Remediation:**
- **Automatische Regelextraktion:** Name-Pattern (`*_7d`, `*_28d`, etc.) → time_window
- **Aufwand:** 1 Stunde (automatisch)
- **Priority:** P0
---
#### 4.2 Code enthält Default-Zeitfenster (20)
Code nutzt `days=X` Parameter, aber Metadaten unknown
**Beispiele:**
- `activity_summary`: Code `days=14` (default), Metadaten unknown
- `sleep_avg_duration`: Code `days=7`, Metadaten unknown
- `rest_days_count`: Code `days=30`, Metadaten unknown
**Remediation:**
- **Code-Parameter-Extraktion:** Default-Werte aus Funktionssignaturen lesen
- **Aufwand:** 2-3 Stunden (semi-automatisch)
- **Priority:** P0
---
#### 4.3 Fach-Entscheidung erforderlich (39)
Zeitfenster nicht aus Name/Code ableitbar, fachliche Klassifizierung nötig
**Kategorien:**
**A. Scores (6):**
- `activity_score`, `nutrition_score`, `recovery_score`, `body_progress_score`, `goal_progress_score`, `data_quality_score`
- **Vorschlag:** `custom` oder `mixed` (kombinieren verschiedene Zeitfenster)
**B. Ability Balance (5):**
- `ability_balance_coordination`, `ability_balance_endurance`, `ability_balance_mental`, `ability_balance_mobility`, `ability_balance_strength`
- **Vorschlag:** `28d` (Rolling-Window-Balance über 28 Tage)
**C. Correlations (5):**
- `correlation_energy_weight_lag`, `correlation_load_hrv`, `correlation_load_rhr`, `correlation_protein_lbm`, `correlation_sleep_recovery`
- **Vorschlag:** `28d` (Min-Daten für reliable Korrelationen)
**D. Goals & Focus (16):**
- `active_goals_json`, `focus_areas_weighted_json`, `top_goal_*`, `top_3_goals_*`, `focus_cat_*`
- **Vorschlag:** `latest` (Snapshot) oder `custom` (je nach Progress-Berechnung)
**E. Snapshots (7):**
- `bmi`, `goal_weight`, `goal_bf_pct`, `waist_hip_ratio`, `recomposition_quadrant`, `plateau_detected`, `top_drivers`
- **Vorschlag:** `latest` (Momentaufnahme) oder `custom` (bei berechneten Werten)
**Remediation:**
- **Fach-Review mit Product:** Kategorisierungs-Entscheidungen abstimmen
- **Aufwand:** 4-6 Stunden (Meeting + Dokumentation)
- **Priority:** P0
---
### CLUSTER 5: Missing Confidence Logic
**Anzahl betroffene Platzhalter:** 103 (93%)
**Severity:** 🟡 HIGH
**Norm-Verstoß:** §5 "Qualitäts-/Confidence-Logik"
**Analyse:**
- Nur 8 Platzhalter haben `confidence_logic` implementiert
- 103 haben `confidence_logic: null`
**Implementierte Confidence (8):**
1. `protein_avg`, `kcal_avg`, `fat_avg`, `carb_avg` (nutrition_metrics)
2. `weight_aktuell`, `weight_trend` (body_metrics)
3. `caliper_summary`, `circ_summary` (body_metrics)
**Pattern:**
```python
confidence = calculate_confidence(data_points, time_window_days, metric_type)
Thresholds:
- high: >= 60% data coverage (e.g., >= 18/30 days)
- medium: >= 40% data coverage (e.g., >= 12/30 days)
- low: >= 26% data coverage (e.g., >= 8/30 days)
- insufficient: < 26% data coverage
```
**Fehlende Confidence-Logik besonders kritisch für:**
#### 5.1 Trend-Platzhalter (11)
**Warum kritisch:** Slopes/Trends mit nur 2-3 Datenpunkten sind unreliabel
| Placeholder | Time-Window | Min-Data empfohlen | Confidence-Logik |
|-------------|-------------|-------|------------------|
| `weight_28d_slope` | 28d | 18+ | ❌ Fehlt |
| `weight_90d_slope` | 90d | 60+ | ❌ Fehlt |
| `weight_7d_median` | 7d | 5+ | ❌ Fehlt |
| `fm_28d_change` | 28d | 2 (min), 18+ (ideal) | ❌ Fehlt |
| `lbm_28d_change` | 28d | 2 (min), 18+ (ideal) | ❌ Fehlt |
| `waist_28d_delta` | 28d | 2 (min) | ❌ Fehlt |
| `hip_28d_delta` | 28d | 2 (min) | ❌ Fehlt |
| `chest_28d_delta` | 28d | 2 (min) | ❌ Fehlt |
| `arm_28d_delta` | 28d | 2 (min) | ❌ Fehlt |
| `thigh_28d_delta` | 28d | 2 (min) | ❌ Fehlt |
| `vo2max_trend_28d` | 28d | 4+ | ❌ Fehlt |
**Remediation:**
- **Pattern-Anwendung:** `calculate_confidence()` in alle Delta/Slope-Funktionen einbauen
- **Aufwand:** 12-16 Stunden
- **Priority:** P1
---
#### 5.2 Score-Platzhalter (6)
**Warum kritisch:** Composite Scores sollten Confidence der Subkomponenten reflektieren
| Placeholder | Sub-Components | Confidence-Logik |
|-------------|----------------|------------------|
| `activity_score` | training_volume, frequency, quality | ❌ Fehlt |
| `nutrition_score` | energy_balance, protein_adequacy, macro_consistency | ❌ Fehlt |
| `recovery_score` | sleep_duration, sleep_quality, hrv, rhr | ❌ Fehlt |
| `body_progress_score` | weight_trend, bf_change, lbm_change | ❌ Fehlt |
| `goal_progress_score` | weighted goals progress | ❌ Fehlt |
| `data_quality_score` | data availability per domain | ❌ Fehlt |
**Remediation:**
- **Composite-Confidence:** Min(subcomponent_confidences)
- **Aufwand:** 8-10 Stunden
- **Priority:** P1
---
#### 5.3 Korrelations-Platzhalter (5)
**Warum kritisch:** Korrelationen mit <14 Paaren sind statistisch unreliabel
| Placeholder | Min-Pairs empfohlen | Confidence-Logik |
|-------------|---------------------|------------------|
| `correlation_energy_weight_lag` | 21+ | ❌ Fehlt |
| `correlation_load_hrv` | 21+ | ❌ Fehlt |
| `correlation_load_rhr` | 21+ | ❌ Fehlt |
| `correlation_protein_lbm` | 28+ (mit Training moderiert) | ❌ Fehlt |
| `correlation_sleep_recovery` | 21+ | ❌ Fehlt |
**Remediation:**
- **Correlation-Confidence:** Based on n_pairs (high >= 28, medium >= 21, low >= 14)
- **Aufwand:** 4-6 Stunden
- **Priority:** P1
---
### CLUSTER 6: Unstrukturierte Missing-Value-Policy
**Anzahl betroffene Platzhalter:** 110 (99%)
**Severity:** 🟡 MEDIUM
**Norm-Verstoß:** §3.5 "Fehlwerte explizit"
**Analyse:**
- 110 haben nur `missing_value_policy.legacy_display: "nicht verfügbar"`
- Nur 1 hat strukturierte Policy (weight_aktuell mit available=false, reason='no_data')
**Problem:**
- Legacy-String ist nicht maschinenlesbar
- Keine Unterscheidung zwischen Fehlertypen:
- `no_data`: Keine Daten in Datenbank
- `insufficient_data`: Zu wenig Daten für Berechnung
- `resolver_error`: Technischer Fehler
- `calculation_error`: Mathematischer Fehler (z.B. Division by zero)
**Norm-konformes Format (§3.5):**
```json
{
"available": false,
"value_raw": null,
"missing_reason": "insufficient_data",
"missing_value_policy": {
"legacy_display": "nicht verfügbar",
"structured_null": true,
"reason_codes": ["no_data", "insufficient_data", "resolver_error"]
}
}
```
**Remediation:**
- **Dual-Mode-Ansatz:**
- Legacy-String beibehalten (Backward-Compatibility)
- Zusätzlich strukturierte Felder (`available`, `missing_reason`, `value_raw`)
- **Aufwand:** 8-10 Stunden (Pattern-Anwendung auf alle Resolver)
- **Priority:** P1
---
### CLUSTER 7: Metadata Completeness Score 0
**Anzahl betroffene Platzhalter:** 111 (100%)
**Severity:** 🟡 MEDIUM
**Norm-Verstoß:** Kein direkter Verstoß, aber Indikator für fehlende Pflichtfelder
**Analyse:**
- Alle 111 haben `metadata_completeness_score: 0`
- Score-Berechnung (vermutlich):
```
score = (filled_fields / total_required_fields) * 100
```
- Da Score 0 → vermutlich wurden Pflichtfelder nicht als "gefüllt" erkannt
**Pflichtfelder (aus Norm §7.1):**
1. `key` ✅ (alle gefüllt)
2. `placeholder` ✅ (alle gefüllt)
3. `category` ❌ (49 Unknown)
4. `type` ✅ (alle gefüllt)
5. `description` ❌ (49 "No description")
6. `semantic_contract` ❌ (49 "No description")
7. `unit` ✅ (alle gefüllt)
8. `time_window` ❌ (74 unknown)
9. `output_type` ✅ (alle gefüllt)
10. `value_display` ❌ (111 null)
11. `available` ✅ (alle true)
12. `missing_value_policy` ✅ (alle gefüllt, aber schwach)
13. `source` ❌ (100 data_layer_module null, 90 source_tables [])
14. `version` ✅ (alle 1.0.0)
15. `deprecated` ✅ (alle false)
**Score 0 Root Cause:**
- Vermutlich zählen `null`/`unknown`/`[]`/`"No description"` als "nicht gefüllt"
- → 7 von 15 Pflichtfeldern nicht korrekt gefüllt = 0% Score
**Remediation:**
- **Nach P0+P1 Fixes:** Score sollte automatisch auf 40-60% steigen
- **Zusätzlich:** value_display für alle Platzhalter füllen (aus Beispieldaten)
- **Aufwand:** Inkludiert in anderen Clustern
- **Priority:** P2 (Indikator-Fix, nicht eigenständig)
---
### CLUSTER 8: Schema Status "draft"
**Anzahl betroffene Platzhalter:** 111 (100%)
**Severity:** 🟡 MEDIUM
**Norm-Verstoß:** §13 Akzeptanzkriterien (production-ready Platzhalter fehlen)
**Analyse:**
- Alle 111 haben `schema_status: draft`
- Keine Platzhalter im Status `production`, `beta`, oder `stable`
**Erlaubte Werte (vermutlich):**
- `draft`: Work in Progress
- `beta`: In Testing
- `stable`: Production-Ready, aber noch nicht finalisiert
- `production`: Voll produktionsreif, Breaking Changes verboten
**Kriterien für `production` (vorgeschlagen):**
1. `metadata_completeness_score >= 80`
2. `used_by.prompts.length >= 1 OR used_by.pipelines.length >= 1`
3. `time_window != 'unknown'`
4. `category != 'Unknown'`
5. `description != 'No description available'`
6. `confidence_logic != null OR type == 'atomic' with time_window == 'latest'`
7. `known_issues.length == 0`
**Kandidaten für `production` nach P0+P1 Fixes:**
- Nutrition Averages (4): protein_avg, kcal_avg, fat_avg, carb_avg
- Body Metrics (2): weight_aktuell, weight_trend
- Profil (4): name, age, height, geschlecht
- Summaries (2): caliper_summary, circ_summary
- **Total: 12-15 Kandidaten**
**Remediation:**
- **Automatische Bewertung:** Script zur Berechnung von Production-Eligibility
- **Manuelle Review:** Product/Tech Lead bestätigt Production-Status
- **Aufwand:** 4-6 Stunden
- **Priority:** P2
---
### CLUSTER 9: Ungenutzte Platzhalter (Orphans)
**Anzahl betroffene Platzhalter:** 67 (60%)
**Severity:** 🟢 LOW (aber Technical Debt)
**Norm-Verstoß:** Kein direkter Verstoß, aber Governance-Issue
**Analyse:**
- 67 Platzhalter haben `used_by.prompts: []`, `used_by.pipelines: []`, `used_by.charts: []`
- 0 Verwendungen = potentielle Deprecation-Kandidaten
**Kategorisierung:**
#### 9.1 Geplante Features (Phase 1b/1c) - behalten (30)
- Correlations (5): energy_weight_lag, load_hrv, load_rhr, protein_lbm, sleep_recovery
- Goals Details (11): active_goals_json/md, focus_areas, top_goals
- Ability Balance (5): coordination, endurance, mental, mobility, strength
- Scores (6): activity_score, nutrition_score, recovery_score, body_progress_score, goal_progress_score, data_quality_score
- Plateau (1): plateau_detected
- Top Drivers (1): top_drivers
- Sleep Debt (1): sleep_debt_hours
#### 9.2 Redundant/Obsolet - Deprecation prüfen (15)
- Body Deltas (4): arm_28d_delta, chest_28d_delta, hip_28d_delta, thigh_28d_delta (redundant zu waist_28d_delta Pattern)
- Training Load (3): monotony_score, strain_score, recent_load_balance_3d (noch nicht genutzt)
- Meta (3): zeitraum_90d, datum_heute (System-Platzhalter, wenig Wert)
- Vitals Trends (2): hrv_vs_baseline_pct, rhr_vs_baseline_pct (noch nicht genutzt)
- Sleep Regularity (1): sleep_regularity_proxy (experimentell)
- BMI (1): bmi (berechenbar, redundant)
- Waist-Hip-Ratio (1): waist_hip_ratio (berechenbar, redundant)
#### 9.3 Unklar - Product-Review (22)
- Rest: Weitere Ability Balance, Focus Cat Weights, etc.
**Remediation:**
- **Product-Review:** Welche für Phase 1b/1c/2 geplant? Welche streichen?
- **Deprecation-Strategie:** `deprecated: true`, `replacement: "new_placeholder"`, Sunset-Datum
- **Aufwand:** 4-6 Stunden (Meeting + Dokumentation)
- **Priority:** P2
---
### CLUSTER 10: Export-Inkonsistenzen
**Anzahl betroffene Platzhalter:** 5 (Meta-Gap)
**Severity:** 🟢 INFO
**Norm-Verstoß:** Kein direkter Verstoß, aber Governance-Issue
**Problem:**
- Export Spec sagt: "116 Platzhalter"
- Extended Catalog + Gap Report: "111 Platzhalter"
- Differenz: 5 Platzhalter
**Analyse:**
- Die 5 zusätzlichen sind vermutlich **Metafelder** im Export:
1. `schema_version`
2. `generated_at`
3. `normative_standard`
4. `total_placeholders`
5. `metadata.summary` (oder ähnlich)
**Remediation:**
- **Dokumentation:** Export-Spec klarstellen (111 User-Placeholders + 5 Metafelder)
- **Aufwand:** 30 Minuten
- **Priority:** P3
---
### CLUSTER 11: Code-Dokumentations-Konflikte
**Anzahl betroffene Platzhalter:** 3 (kritische Konflikte)
**Severity:** 🔴 CRITICAL
**Norm-Verstoß:** §2 "Vorrang" (Code > Docs bei Konflikt)
**Konflikte:**
#### 11.1 weight_trend
- **Description:** "Gewichtstrend (7d/30d)"
- **Code:** `get_weight_trend_data(profile_id, days=28)`
- **Metadaten:** `time_window: unknown`
- **Used-By:** 10 Prompts/Pipelines
- **Impact:** 🔴 HIGH (Prompts gehen von 7d/30d aus, erhalten aber 28d)
**Fix:**
```
description: "Gewichtstrend 28d (lineare Regression)"
semantic_contract: "Lineare Regression über 28 Tage, Richtung + Delta"
time_window: "28d"
```
---
#### 11.2 activity_summary
- **Description:** "Aktivitäts-Zusammenfassung (7d)"
- **Code:** `get_activity_summary_data(profile_id, days=14)`
- **Metadaten:** `time_window: unknown`
- **Used-By:** 2 Prompts
- **Impact:** 🟡 MEDIUM (weniger Verwendungen, aber Inkonsistenz)
**Fix:**
```
description: "Aktivitäts-Zusammenfassung 14d"
semantic_contract: "Aggregierte Aktivitäts-Metriken über 14 Tage"
time_window: "14d"
```
---
#### 11.3 activity_detail
- **Description:** "Keine explizite Zeitangabe"
- **Code:** `get_activity_detail_data(profile_id, days=14, limit=20)`
- **Metadaten:** `time_window: unknown`
- **Used-By:** 4 Prompts
- **Impact:** 🟡 MEDIUM
**Fix:**
```
description: "Detaillierte Aktivitäts-Liste 14d (max 20 Einträge)"
semantic_contract: "Sortierte Liste letzter 20 Aktivitäten aus 14-Tage-Fenster"
time_window: "14d"
```
---
**Remediation:**
- **Sofortige Korrektur:** Description, semantic_contract, time_window auf Code-Wahrheit setzen
- **Aufwand:** 1 Stunde
- **Priority:** P0
---
## GAP-CLUSTER ZUSAMMENFASSUNG
| Cluster | Platzhalter | Severity | Priority | Aufwand | Abhängigkeiten |
|---------|-------------|----------|----------|---------|----------------|
| **1. Semantic Contract** | 49 | 🔴 CRITICAL | P0 | 4-6h | Keine |
| **2. Data Layer Module** | 100 | 🔴 CRITICAL | P1 | 6-8h | Cluster 1 |
| **3. Source Tables** | 90 | 🔴 CRITICAL | P1 | 6-8h | Cluster 1 |
| **4. Time Window** | 74 | 🔴 CRITICAL | P0 | 6-10h | Keine |
| **5. Confidence Logic** | 103 | 🟡 HIGH | P1 | 24-32h | Cluster 4 |
| **6. Missing-Value-Policy** | 110 | 🟡 MEDIUM | P1 | 8-10h | Cluster 5 |
| **7. Completeness Score 0** | 111 | 🟡 MEDIUM | P2 | Inkludiert | Nach P0+P1 |
| **8. Schema Status draft** | 111 | 🟡 MEDIUM | P2 | 4-6h | Nach P0+P1 |
| **9. Ungenutzte Platzhalter** | 67 | 🟢 LOW | P2 | 4-6h | Product-Review |
| **10. Export-Inkonsistenzen** | 5 | 🟢 INFO | P3 | 0.5h | Keine |
| **11. Code-Docs-Konflikte** | 3 | 🔴 CRITICAL | P0 | 1h | Keine |
**Gesamt-Remediationsaufwand:** 64-87 Stunden (gestaffelt über P0-P3)
---
## REMEDIATION-PRIORISIERUNG
### P0 (BLOCKING - Week 1)
1. **Cluster 11:** Code-Docs-Konflikte (1h)
2. **Cluster 1:** Semantic Contract (4-6h)
3. **Cluster 4:** Time Window (6-10h)
- **Sub:** Name-Pattern (1h, automatisch)
- **Sub:** Code-Parameter (2-3h, semi-automatisch)
- **Sub:** Fach-Entscheidung (4-6h, manuell mit Product)
**Total P0:** 11-17 Stunden
---
### P1 (HIGH - Week 2-3)
1. **Cluster 2:** Data Layer Module (6-8h)
2. **Cluster 3:** Source Tables (6-8h)
3. **Cluster 5:** Confidence Logic (24-32h)
- **Sub:** Trend-Platzhalter (12-16h)
- **Sub:** Score-Platzhalter (8-10h)
- **Sub:** Korrelations-Platzhalter (4-6h)
4. **Cluster 6:** Missing-Value-Policy (8-10h)
**Total P1:** 44-58 Stunden
---
### P2 (MEDIUM - Week 4-5)
1. **Cluster 7:** Completeness Score (inkludiert in P0+P1)
2. **Cluster 8:** Schema Status Production (4-6h)
3. **Cluster 9:** Ungenutzte Platzhalter Review (4-6h)
**Total P2:** 8-12 Stunden
---
### P3 (LOW - Later)
1. **Cluster 10:** Export-Inkonsistenzen Doku (0.5h)
**Total P3:** 0.5 Stunden
---
**GESAMT:** 63.5-87.5 Stunden über 4-6 Wochen
---
## NÄCHSTE SCHRITTE
1. **Review dieses Gap-Reports** mit Tech Lead
2. **Priorisierungs-Bestätigung:** P0-Liste final absegnen
3. **Kickoff P0-Sprint:**
- Code-Docs-Konflikte sofort fixen (1h)
- Semantic Contract Bulk-Update (4-6h)
- Zeitfenster-Klassifizierung (6-10h)
4. **Nach P0:** P1-Sprint planen (Confidence + Data Layer + Missing-Value)
**Zie
l nach P0+P1:** 60-70% Normkonformität erreicht
---
**Audit-Report erstellt von:** Claude Code (Lead Audit Agent)
**Basis:** 4-Agent-Analyse (Code-Evidence, Semantic-Contract, Time-Window-Confidence, Prompt-Usage)
@@ -0,0 +1,983 @@
# Priorisierter Maßnahmenplan: Placeholder-Remediation
**Audit-Datum:** 29. März 2026
**Basis:** Gap-Cluster-Analyse, 111 Platzhalter
**Ziel:** Normkonformität auf 60-70% steigern (aktuell 7%)
---
## ROADMAP-ÜBERSICHT
| Phase | Fokus | Dauer | Aufwand | Ziel-Compliance |
|-------|-------|-------|---------|-----------------|
| **P0** | Blocking Issues | Week 1 | 11-17h | 25-30% |
| **P1** | High Priority Gaps | Week 2-3 | 44-58h | 50-60% |
| **P2** | Medium Priority | Week 4-5 | 8-12h | 65-70% |
| **P3** | Nice-to-Have | Later | 0.5h | 70%+ |
| **TOTAL** | | 4-6 Wochen | 63.5-87.5h | 70%+ |
---
## P0: BLOCKING ISSUES (Week 1)
**Ziel:** Kritische Inkonsistenzen und Pflichtfelder beheben
**Aufwand:** 11-17 Stunden
**Team:** 1-2 Entwickler
**Dependencies:** Keine - sofort startbar
---
### P0.1: Code-Dokumentations-Konflikte (SOFORT)
**Gap-Cluster:** 11
**Betroffene Platzhalter:** 3 (weight_trend, activity_summary, activity_detail)
**Severity:** 🔴 CRITICAL
**Aufwand:** 1 Stunde
**Maßnahmen:**
1. **weight_trend Fix**
```diff
# PLACEHOLDER_CATALOG_EXTENDED.json
{
"key": "weight_trend",
- "description": "Gewichtstrend (7d/30d)",
+ "description": "Gewichtstrend 28d (lineare Regression)",
- "semantic_contract": "Gewichtstrend (7d/30d)",
+ "semantic_contract": "Lineare Regression über 28 Tage, Richtung + Delta in kg",
- "time_window": "unknown",
+ "time_window": "28d",
}
```
2. **activity_summary Fix**
```diff
{
"key": "activity_summary",
- "description": "Aktivitäts-Zusammenfassung (7d)",
+ "description": "Aktivitäts-Zusammenfassung 14d",
- "semantic_contract": "Aktivitäts-Zusammenfassung (7d)",
+ "semantic_contract": "Aggregierte Aktivitäts-Metriken über 14 Tage",
- "time_window": "unknown",
+ "time_window": "14d",
}
```
3. **activity_detail Fix**
```diff
{
"key": "activity_detail",
- "description": "No description available",
+ "description": "Detaillierte Aktivitäts-Liste 14d (max 20 Einträge)",
- "semantic_contract": "No description available",
+ "semantic_contract": "Sortierte Liste letzter 20 Aktivitäten aus 14-Tage-Fenster, DESC nach Datum",
- "time_window": "unknown",
+ "time_window": "14d",
}
```
**Validation:**
- Code-Review: Zeitfenster im Code bestätigen
- Prompt-Review: Alle 10+2+4 betroffenen Prompts/Pipelines prüfen
**Owner:** Backend Lead
**Blocker:** Keine
**Output:** 3 Fixed Platzhalter, Updated Catalog
---
### P0.2: Zeitfenster Name-Pattern (AUTOMATISCH)
**Gap-Cluster:** 4.1
**Betroffene Platzhalter:** 15 (zeitraum_*, sleep_*_7d, training_frequency_7d, etc.)
**Severity:** 🔴 CRITICAL
**Aufwand:** 1 Stunde (automatisches Skript)
**Maßnahmen:**
**Skript: `fix_time_window_from_name.py`**
```python
import json
import re
# Regex-Pattern für Zeitfenster im Namen
patterns = {
r'_7d$|_7d_': '7d',
r'_14d$|_14d_': '14d',
r'_28d$|_28d_': '28d',
r'_30d$|_30d_': '30d',
r'_90d$|_90d_': '90d',
}
catalog = load_catalog()
fixes = []
for placeholder in catalog['placeholders'].values():
key = placeholder['key']
# Überspringe bereits definierte
if placeholder['time_window'] != 'unknown':
continue
# Pattern-Match
for pattern, window in patterns.items():
if re.search(pattern, key):
placeholder['time_window'] = window
fixes.append(f"{key}: unknown → {window}")
break
print(f"Fixed {len(fixes)} placeholders")
save_catalog(catalog)
```
**Erwartete Fixes:**
- `zeitraum_7d`: unknown → 7d
- `zeitraum_30d`: unknown → 30d
- `zeitraum_90d`: unknown → 90d
- `sleep_avg_duration_7d`: unknown → 7d
- `sleep_quality_7d`: unknown → 7d
- `training_frequency_7d`: unknown → 7d
- `proxy_internal_load_7d`: unknown → 7d
- `energy_balance_7d`: unknown → 7d
- `protein_adequacy_28d`: unknown → 28d
- ... (insgesamt ~15)
**Validation:**
- Manuelle Review der Auto-Fixes
- Diff-Check vor Commit
**Owner:** DevOps / Automation
**Blocker:** Keine
**Output:** 15 Fixed Platzhalter
---
### P0.3: Zeitfenster Code-Parameter (SEMI-AUTOMATISCH)
**Gap-Cluster:** 4.2
**Betroffene Platzhalter:** ~20 (activity_summary, sleep_avg_duration, rest_days_count, etc.)
**Severity:** 🔴 CRITICAL
**Aufwand:** 2-3 Stunden
**Maßnahmen:**
1. **Code-Parameter-Extraktion**
- Suche in `placeholder_resolver.py` nach `days=X` Parametern
- Greppen in `data_layer/*.py` nach Default-Werten
```bash
# Beispiel-Grep
grep -n "def get_.*_data.*days=" backend/data_layer/*.py
grep -n "lambda.*days=" backend/placeholder_resolver.py
```
2. **Manuelle Zuordnung**
- Für jeden Treffer: Placeholder Key identifizieren
- Default-Wert → time_window setzen
**Erwartete Fixes:**
- `sleep_avg_duration`: Code `days=7` → time_window: 7d
- `rest_days_count`: Code `days=30` → time_window: 30d
- `nutrition_days`: Code `days=30` → time_window: 30d
- ... (~20 total)
**Validation:**
- Code-Review der Mappings
- Stichproben-Tests
**Owner:** Backend Developer
**Blocker:** P0.2 abgeschlossen
**Output:** 20 Fixed Platzhalter
---
### P0.4: Semantic Contract Bulk-Update
**Gap-Cluster:** 1.1
**Betroffene Platzhalter:** 49 ("No description available")
**Severity:** 🔴 CRITICAL
**Aufwand:** 4-6 Stunden
**Maßnahmen:**
**Input:** Semantic-Contract-Agent-Report (bereits vorhanden)
**Prozess:**
1. Für jeden der 49 Platzhalter:
- `description` aus Agent-Report übernehmen
- `semantic_contract` aus Agent-Report übernehmen
- `category` aus Agent-Report setzen (statt "Unknown")
2. Bulk-Update via JSON-Merge-Skript
3. Manuelle Review der Top-10 kritischsten (nach Usage)
**Beispiel-Update (ability_balance_coordination):**
```diff
{
"key": "ability_balance_coordination",
- "category": "Unknown",
+ "category": "Training",
- "description": "No description available",
+ "description": "Koordinationsfähigkeit-Balance-Anteil (%)",
- "semantic_contract": "No description available",
+ "semantic_contract": "Gewichteter Anteil der Trainings-Last für Koordinations-Fähigkeit über 28-Tage-Fenster",
- "time_window": "unknown",
+ "time_window": "28d",
}
```
**Prioritäts-Reihenfolge (nach Usage):**
1. Goals & Focus (16) - 7 produktkritisch
2. Correlations (5) - experimentell, aber wichtig
3. Body Deltas (5) - Körper-Tracking
4. Nutrition (6) - Ernährungs-Metriken
5. Training (8) - Ability Balance, Load
6. Summaries (3) - circ_summary, caliper_summary
7. Meta (2) - zeitraum_90d
8. Plateau (1) - plateau_detected
9. Top Drivers (1) - top_drivers
**Validation:**
- Review der Top-10 produktkritischsten Platzhalter manuell
- Stichprobe 10% der restlichen
- Automated Consistency Check (keine "No description" mehr)
**Owner:** Backend Lead + Product (für fachliche Review)
**Blocker:** Keine
**Output:** 49 Fixed Platzhalter, alle mit Kategorie + Description
---
### P0.5: Zeitfenster Fach-Entscheidung
**Gap-Cluster:** 4.3
**Betroffene Platzhalter:** ~39 (Scores, Ability Balance, Correlations, Goals, Snapshots)
**Severity:** 🔴 CRITICAL
**Aufwand:** 4-6 Stunden (Meeting + Dokumentation)
**Maßnahmen:**
**Phase 1: Kategorisierung (2h)**
- Product + Tech Meeting
- Entscheidung pro Kategorie:
| Kategorie | Platzhalter | Vorschlag | Rationale |
|-----------|-------------|-----------|-----------|
| **Scores (6)** | activity_score, nutrition_score, recovery_score, body_progress_score, goal_progress_score, data_quality_score | `custom` oder `mixed` | Kombinieren verschiedene Zeitfenster |
| **Ability Balance (5)** | coordination, endurance, mental, mobility, strength | `28d` | Rolling-Window über 28 Tage |
| **Correlations (5)** | energy_weight_lag, load_hrv, load_rhr, protein_lbm, sleep_recovery | `28d` | Min-Daten für Reliability |
| **Goals & Focus (16)** | active_goals_json, focus_areas_*, top_goal_*, top_3_goals_*, focus_cat_* | `latest` (Snapshot) oder `custom` | Je nach Progress-Berechnung |
| **Snapshots (7)** | bmi, goal_weight, goal_bf_pct, waist_hip_ratio, recomposition_quadrant, plateau_detected, top_drivers | `latest` oder `custom` | Momentaufnahme vs. Berechnet |
**Phase 2: Dokumentation (2h)**
- Entscheidungen in Decision-Log festhalten
- time_window-Werte in Catalog setzen
- Semantic Contracts anpassen (Zeit-Bezug aufnehmen)
**Phase 3: Validation (1h)**
- Review mit Stakeholdern
- Prompt-Autoren informieren (Breaking Change bei "custom" → spezifisches Fenster)
**Owner:** Product Manager + Tech Lead
**Blocker:** P0.4 Semantic Contract abgeschlossen
**Output:** Decision-Log, 39 Fixed Platzhalter
---
### P0 SUMMARY
**Gesamt-Aufwand:** 11-17 Stunden
**Deliverables:**
- 3 Code-Docs-Konflikte gelöst
- 74 time_window: unknown → definierte Werte
- 49 description/category: Unknown/No description → vollständig
- **Total Fixed:** 77 Platzhalter (15+20+39+3 unique)
**Impact:**
- **Compliance:** 7% → 25-30%
- **Blocked Gaps:** time_window, description, category, code-conflicts
**Next:** P1 kann starten (Confidence, Data Layer, Source Tables)
---
## P1: HIGH PRIORITY (Week 2-3)
**Ziel:** Technische Tiefe hinzufügen (Confidence, Data Layer, Source Tables)
**Aufwand:** 44-58 Stunden
**Team:** 2-3 Entwickler
**Dependencies:** P0 abgeschlossen
---
### P1.1: Confidence-Logik für Trend-Platzhalter
**Gap-Cluster:** 5.1
**Betroffene Platzhalter:** 11 (weight_*_slope, *_28d_delta, vo2max_trend_28d)
**Severity:** 🟡 HIGH
**Aufwand:** 12-16 Stunden
**Maßnahmen:**
**Pattern:**
```python
# In data_layer/body_metrics.py
def calculate_weight_28d_slope(profile_id: int, conn):
"""Gewichtstrend über 28 Tage mit Confidence."""
# 1. Daten holen
rows = fetch_weight_data(profile_id, days=28, conn=conn)
# 2. Confidence berechnen
confidence = calculate_confidence(
data_points=len(rows),
time_window_days=28,
metric_type='trend'
)
if confidence == 'insufficient':
return {
'slope': None,
'confidence': 'insufficient',
'data_points': len(rows),
'min_required': 8 # 28% coverage
}
# 3. Slope berechnen (nur wenn sufficient)
slope = linear_regression_slope(rows)
return {
'slope': slope,
'confidence': confidence, # high/medium/low
'data_points': len(rows),
'r_squared': calculate_r_squared(rows, slope)
}
```
**Thresholds (trend-specific):**
```python
def calculate_confidence(data_points, time_window_days, metric_type):
coverage = data_points / time_window_days
if metric_type == 'trend':
# Strengere Thresholds für Trends
if coverage >= 0.70: # >= 70%
return 'high'
elif coverage >= 0.50: # >= 50%
return 'medium'
elif coverage >= 0.30: # >= 30%
return 'low'
else:
return 'insufficient'
# ... andere Typen
```
**Zu implementieren für:**
1. `weight_28d_slope` (28d, min 8, ideal 20)
2. `weight_90d_slope` (90d, min 27, ideal 63)
3. `weight_7d_median` (7d, min 3, ideal 5)
4. `fm_28d_change` (28d, min 2, ideal 18)
5. `lbm_28d_change` (28d, min 2, ideal 18)
6. `waist_28d_delta` (28d, min 2, ideal 18)
7. `hip_28d_delta` (28d, min 2, ideal 18)
8. `chest_28d_delta` (28d, min 2, ideal 18)
9. `arm_28d_delta` (28d, min 2, ideal 18)
10. `thigh_28d_delta` (28d, min 2, ideal 18)
11. `vo2max_trend_28d` (28d, min 4, ideal 18)
**Testing:**
- Unit-Tests für calculate_confidence() mit verschiedenen Coverages
- Integration-Tests mit real data (0%, 30%, 50%, 70%, 100% coverage)
- Regression-Tests (alte Werte ohne Confidence bleiben gleich)
**Owner:** Backend Developer (Senior)
**Blocker:** P0 time_window abgeschlossen
**Output:** 11 Platzhalter mit Confidence-Logik
---
### P1.2: Confidence-Logik für Score-Platzhalter
**Gap-Cluster:** 5.2
**Betroffene Platzhalter:** 6 (activity_score, nutrition_score, recovery_score, etc.)
**Severity:** 🟡 HIGH
**Aufwand:** 8-10 Stunden
**Maßnahmen:**
**Composite-Confidence-Pattern:**
```python
def calculate_nutrition_score(profile_id: int, conn):
"""Nutrition Score mit Composite Confidence."""
# 1. Sub-Scores berechnen (mit eigenen Confidences)
energy_balance = calculate_energy_balance_7d(profile_id, conn)
protein_adequacy = calculate_protein_adequacy_28d(profile_id, conn)
macro_consistency = calculate_macro_consistency_score(profile_id, conn)
# 2. Composite Confidence = MIN(sub-confidences)
confidence_levels = ['high', 'medium', 'low', 'insufficient']
confidences = [
energy_balance['confidence'],
protein_adequacy['confidence'],
macro_consistency['confidence']
]
# Min-Confidence
min_confidence = min(confidences, key=lambda c: confidence_levels.index(c))
if min_confidence == 'insufficient':
return {
'score': None,
'confidence': 'insufficient',
'sub_scores': {...},
'note': 'Mindestens eine Komponente hat insufficient data'
}
# 3. Score berechnen (gewichtet)
score = (
energy_balance['score'] * 0.4 +
protein_adequacy['score'] * 0.4 +
macro_consistency['score'] * 0.2
)
return {
'score': round(score),
'confidence': min_confidence,
'sub_scores': {
'energy_balance': energy_balance,
'protein_adequacy': protein_adequacy,
'macro_consistency': macro_consistency
}
}
```
**Zu implementieren für:**
1. `activity_score` (training_volume + frequency + quality)
2. `nutrition_score` (energy_balance + protein_adequacy + macro_consistency)
3. `recovery_score` (sleep_duration + sleep_quality + hrv + rhr)
4. `body_progress_score` (weight_trend + bf_change + lbm_change)
5. `goal_progress_score` (weighted goals progress)
6. `data_quality_score` (data availability per domain)
**Testing:**
- Scenario-Tests: alle Sub-Scores high → Composite high
- Scenario-Tests: eine Sub-Score insufficient → Composite insufficient
- Edge-Cases: missing Sub-Components
**Owner:** Backend Developer (Mid/Senior)
**Blocker:** P1.1 Trend-Confidence abgeschlossen (Pattern etabliert)
**Output:** 6 Platzhalter mit Composite Confidence
---
### P1.3: Confidence-Logik für Korrelations-Platzhalter
**Gap-Cluster:** 5.3
**Betroffene Platzhalter:** 5 (correlation_*)
**Severity:** 🟡 HIGH
**Aufwand:** 4-6 Stunden
**Maßnahmen:**
**Correlation-Confidence-Pattern:**
```python
def calculate_lag_correlation(profile_id, metric_a, metric_b, lag_days=[0,3,7,14], conn):
"""Lag-Korrelation mit Pair-basiertem Confidence."""
results = []
for lag in lag_days:
pairs = fetch_paired_data(profile_id, metric_a, metric_b, lag, conn)
n_pairs = len(pairs)
# Confidence basierend auf Anzahl Paare
if n_pairs >= 28:
confidence = 'high'
elif n_pairs >= 21:
confidence = 'medium'
elif n_pairs >= 14:
confidence = 'low'
else:
confidence = 'insufficient'
if confidence == 'insufficient':
correlation = None
else:
correlation = pearson_correlation(pairs)
results.append({
'lag_days': lag,
'correlation': correlation,
'n_pairs': n_pairs,
'confidence': confidence,
'note': 'explorativ, nicht kausal'
})
return {
'correlations': results,
'overall_confidence': min([r['confidence'] for r in results])
}
```
**Zu implementieren für:**
1. `correlation_energy_weight_lag` (min 21 Paare)
2. `correlation_load_hrv` (min 21 Paare)
3. `correlation_load_rhr` (min 21 Paare)
4. `correlation_protein_lbm` (min 28 Paare, Training moderiert)
5. `correlation_sleep_recovery` (min 21 Paare)
**Testing:**
- Synthetic Data: 10, 14, 21, 28, 35 Paare → Confidence-Check
- Real Data: Validate gegen tatsächliche Daten-Dichte
**Owner:** Backend Developer (Senior, Statistik-Know-how)
**Blocker:** P1.1 Confidence-Pattern etabliert
**Output:** 5 Platzhalter mit Correlation-Confidence
---
### P1.4: Data-Layer-Module dokumentieren
**Gap-Cluster:** 2
**Betroffene Platzhalter:** 100 (data_layer_module: null)
**Severity:** 🔴 CRITICAL
**Aufwand:** 6-8 Stunden
**Maßnahmen:**
**Input:** Code-Evidence-Agent-Report (technische Herkunft für alle 111)
**Prozess:**
1. **Mapping-Extraktion:**
- Für jede `_safe_*`-Funktion: Gerufene Data-Layer-Funktion identifizieren
- Mapping: Placeholder Key → Data-Layer-Module
2. **Bulk-Update-Skript:**
```python
# Mapping aus Code-Evidence-Report
data_layer_mapping = {
'goal_progress_score': 'data_layer.scores',
'body_progress_score': 'data_layer.body_metrics',
'nutrition_score': 'data_layer.nutrition_metrics',
'activity_score': 'data_layer.activity_metrics',
'recovery_score': 'data_layer.recovery_metrics',
# ... 95 more
}
# Catalog Update
for key, module in data_layer_mapping.items():
catalog['placeholders'][key]['source']['data_layer_module'] = module
```
3. **Validation:**
- Automated Check: Alle 111 haben data_layer_module gesetzt
- Stichprobe 10%: Manuell im Code validieren
**Owner:** DevOps / Backend Lead
**Blocker:** Code-Evidence-Agent-Report finalisiert (✓)
**Output:** 100 Fixed Platzhalter
---
### P1.5: Source-Tables dokumentieren
**Gap-Cluster:** 3
**Betroffene Platzhalter:** 90 (source_tables: [])
**Severity:** 🔴 CRITICAL
**Aufwand:** 6-8 Stunden
**Maßnahmen:**
**Identisch zu P1.4:**
- Mapping aus Code-Evidence-Report übernehmen
- Bulk-Update-Skript
- Validation
**Mapping-Beispiel:**
```python
source_tables_mapping = {
'weight_aktuell': ['weight_log'],
'weight_trend': ['weight_log'],
'kf_aktuell': ['caliper_log'],
'bmi': ['weight_log', 'profiles'],
'nutrition_score': ['nutrition_log'],
'activity_score': ['activity_log'],
'recovery_score': ['sleep_log', 'vitals_baseline', 'rest_days'],
# ... 83 more
}
```
**Owner:** DevOps / Backend Lead
**Blocker:** Code-Evidence-Agent-Report finalisiert (✓)
**Output:** 90 Fixed Platzhalter
---
### P1.6: Strukturierte Missing-Value-Policy
**Gap-Cluster:** 6
**Betroffene Platzhalter:** 110 (nur legacy_display)
**Severity:** 🟡 MEDIUM
**Aufwand:** 8-10 Stunden
**Maßnahmen:**
**Dual-Mode-Ansatz:**
```python
# Alte Resolver-Return (Backward-Compatible)
def get_weight_trend(profile_id, days=28, conn=None):
data = get_weight_trend_data(profile_id, days, conn)
if data['confidence'] == 'insufficient':
# Legacy: String-Return
return "nicht verfügbar"
return f"{data['direction']} {data['delta']} kg"
# Neue Structured-Return (Parallel)
def get_weight_trend_structured(profile_id, days=28, conn=None):
data = get_weight_trend_data(profile_id, days, conn)
if data['confidence'] == 'insufficient':
return {
'available': False,
'value_raw': None,
'value_display': "nicht verfügbar",
'missing_reason': 'insufficient_data',
'missing_value_policy': {
'legacy_display': "nicht verfügbar",
'structured_null': True,
'reason_codes': ['no_data', 'insufficient_data', 'resolver_error']
},
'metadata': {
'data_points': data['data_points'],
'min_required': data['min_required'],
'time_window': '28d'
}
}
return {
'available': True,
'value_raw': data['slope'],
'value_display': f"{data['direction']} {data['delta']} kg",
'confidence': data['confidence'],
'metadata': {
'data_points': data['data_points'],
'r_squared': data['r_squared'],
'time_window': '28d'
}
}
```
**Migration-Strategie:**
1. **Phase 1:** Neue `*_structured()`-Funktionen neben alten (Parallel)
2. **Phase 2:** Extended Export nutzt structured
3. **Phase 3:** Legacy-Export bleibt unverändert (Backward-Compat)
4. **Phase 4 (Later):** Deprecate alte Funktionen nach 6-12 Monaten
**Zu implementieren für:**
- Alle 110 Platzhalter (außer weight_aktuell, der bereits structured ist)
**Testing:**
- Legacy-Tests: Alte Funktionen bleiben unverändert
- Structured-Tests: Neue Funktionen returnieren korrekte Struktur
- Export-Tests: Extended Export nutzt structured
**Owner:** Backend Team (2 Entwickler)
**Blocker:** P1.1-P1.3 Confidence abgeschlossen
**Output:** 110 Platzhalter mit Dual-Mode-Support
---
### P1 SUMMARY
**Gesamt-Aufwand:** 44-58 Stunden
**Deliverables:**
- 11 Trend-Platzhalter mit Confidence
- 6 Score-Platzhalter mit Composite Confidence
- 5 Correlation-Platzhalter mit Pair-Confidence
- 100 Platzhalter mit data_layer_module
- 90 Platzhalter mit source_tables
- 110 Platzhalter mit Structured Missing-Value-Policy
- **Total Fixed:** 103 unique Platzhalter (alle außer 8 bereits conforme)
**Impact:**
- **Compliance:** 25-30% → 50-60%
- **Blocked Gaps:** Confidence, Data Layer, Source Tables, Missing-Value-Policy
**Next:** P2 Production-Ready + Deprecation
---
## P2: MEDIUM PRIORITY (Week 4-5)
**Ziel:** Production-Status und Deprecation-Strategie
**Aufwand:** 8-12 Stunden
**Team:** Product + Tech Lead
**Dependencies:** P1 abgeschlossen
---
### P2.1: Schema-Status auf Production (Top 20)
**Gap-Cluster:** 8
**Betroffene Platzhalter:** 20-30 Kandidaten
**Severity:** 🟡 MEDIUM
**Aufwand:** 4-6 Stunden
**Maßnahmen:**
**Kriterien für `schema_status: production`:**
1. `metadata_completeness_score >= 80`
2. `used_by.prompts.length >= 1 OR used_by.pipelines.length >= 1`
3. `time_window != 'unknown'`
4. `category != 'Unknown'`
5. `description != 'No description available'`
6. `confidence_logic != null OR (type == 'atomic' AND time_window == 'latest')`
7. `known_issues.length == 0`
**Prozess:**
1. **Automated Eligibility-Check:**
```python
def is_production_ready(placeholder):
checks = [
placeholder['metadata_completeness_score'] >= 80,
len(placeholder['used_by']['prompts']) >= 1 or
len(placeholder['used_by']['pipelines']) >= 1,
placeholder['time_window'] != 'unknown',
placeholder['category'] != 'Unknown',
placeholder['description'] != 'No description available',
placeholder['confidence_logic'] is not None or
(placeholder['type'] == 'atomic' and placeholder['time_window'] == 'latest'),
len(placeholder['known_issues']) == 0
]
return all(checks)
```
2. **Kandidaten-Liste generieren**
3. **Manuelle Review** (Product + Tech Lead)
- Sind diese wirklich production-ready?
- Fehlt noch etwas?
4. **Schema-Status-Update**
**Erwartete Kandidaten (12-15):**
- Nutrition Averages (4): protein_avg, kcal_avg, fat_avg, carb_avg
- Body Metrics (3): weight_aktuell, weight_trend, kf_aktuell
- Profil (4): name, age, height, geschlecht
- Summaries (2): caliper_summary, circ_summary
- Goals (2-3): goal_weight, goal_bf_pct, top_goal_name
**Owner:** Tech Lead + Product Manager
**Blocker:** P1 abgeschlossen (Confidence, Data Layer)
**Output:** 12-15 Platzhalter mit `schema_status: production`
---
### P2.2: Ungenutzte Platzhalter - Integration planen
**Gap-Cluster:** 9 (REINTERPRETIERT: Nicht Deprecation, sondern Integration)
**Betroffene Platzhalter:** 67 (ungenutzt)
**Severity:** 🟡 MEDIUM (Prompt-Bibliothek Vollständigkeit)
**Aufwand:** 4-6 Stunden
**Maßnahmen:**
**Neue Klassifizierung (siehe USAGE_ROLE_CLASSIFICATION.md):**
1. **unused_but_planned (30)** - Explizit in Roadmap Phase 0c/1/2
- Scores (6), Correlations (5), Ability Balance (5), Goals Details (11), etc.
- **Action:** Timeline bestätigen, Prototyping-Prompts erstellen
2. **unused_but_plausible (37)** - Fachlich sinnvoll, noch nicht in Prompts
- Body Deltas, Nutrition Details, Training Quality, Focus Category, Meta
- **Action:** Prompt-Use-Cases identifizieren, Templates für Quick Wins
3. **redundant_or_duplicate (0)** - Keine!
- Alle 67 haben fachliche Berechtigung
**Prozess:**
1. **Meeting (2h):** Product + Tech Review aller 67
- Gruppe A (30 geplant): Timeline bestätigen (Phase 0c/1/2)
- Gruppe B (37 plausibel): Prompt-Use-Cases identifizieren (10-15 Quick Wins)
2. **Dokumentation (1h):** Integration-Roadmap, Prompt-Kandidaten-Liste
3. **Implementation (1-2h):** Prompt-Templates erstellen (5-10 Quick Wins)
4. **Communication (1h):** Prompt-Autoren: "Neue Platzhalter verfügbar"
**Integration-Beispiel (statt Deprecation):**
```json
{
"key": "arm_28d_delta",
"usage_role": "unused_but_plausible",
"integration_priority": "medium",
"prompt_use_cases": [
"Fortschritts-Analyse spezifischer Körperteile",
"Asymmetrie-Erkennung (linker vs. rechter Arm)",
"Trainingsplan-Effektivität (Armtraining Tracking)"
],
"example_prompt_template": "Deine Armumfänge haben sich in den letzten 28 Tagen um {{arm_28d_delta}}cm verändert. Analyse: ..."
}
```
**Owner:** Product Manager + Tech Lead
**Blocker:** P1 abgeschlossen
**Output:** Integration-Roadmap, Prompt-Templates (5-10), Nutzungsrate +10-20%
---
### P2 SUMMARY
**Gesamt-Aufwand:** 8-12 Stunden
**Deliverables:**
- 12-15 Production-Ready Platzhalter
- Integration-Roadmap für 30 geplante Platzhalter (Phase 0c/1/2)
- Prompt-Templates für 5-10 Quick Wins (ungenutzte Platzhalter aktivieren)
**Impact:**
- **Compliance:** 50-60% → 65-70%
- **Governance:** Production-Pipeline etabliert, Placeholder-Integration vorangetrieben
- **Nutzungsrate:** 40% → 50-60% (organisch durch Integration)
**Next:** P3 (Nice-to-Have)
---
## P3: NICE-TO-HAVE (Later)
**Ziel:** Dokumentations-Feinschliff
**Aufwand:** 0.5 Stunden
**Team:** Tech Writer / DevOps
**Dependencies:** P2 abgeschlossen
---
### P3.1: Export-Inkonsistenzen Dokumentation
**Gap-Cluster:** 10
**Betroffene:** Dokumentation
**Severity:** 🟢 INFO
**Aufwand:** 0.5 Stunden
**Maßnahmen:**
**Export Spec Update:**
```diff
# PLACEHOLDER_EXPORT_SPEC.md
- **Total Placeholders:** 116
+ **User Placeholders:** 111
+ **Meta Fields:** 5 (schema_version, generated_at, normative_standard, total_placeholders, metadata.summary)
+ **Total Export Entries:** 116
```
**Owner:** Tech Writer
**Blocker:** Keine
**Output:** Updated Export Spec
---
## ERFOLGS-METRIKEN
### Nach P0 (Week 1)
- ✅ **Compliance:** 7% → 25-30%
- ✅ **time_window: unknown:** 74 → 0
- ✅ **category: Unknown:** 49 → 0
- ✅ **description: No description:** 49 → 0
- ✅ **Code-Docs-Konflikte:** 3 → 0
### Nach P1 (Week 3)
- ✅ **Compliance:** 25-30% → 50-60%
- ✅ **Confidence-Logik:** 8 → 28 (Trend + Score + Correlation)
- ✅ **data_layer_module:** 11 → 111
- ✅ **source_tables:** 21 → 111
- ✅ **Structured Missing-Value:** 1 → 111
### Nach P2 (Week 5)
- ✅ **Compliance:** 50-60% → 65-70%
- ✅ **schema_status: production:** 0 → 12-15
- ✅ **deprecated:** 0 → 15-20
- ✅ **Technical Debt:** Reduziert
### Nach P3
- ✅ **Compliance:** 65-70% → 70%+
- ✅ **Dokumentation:** Vollständig konsistent
---
## RISIKEN & MITIGATION
| Risiko | Wahrscheinlichkeit | Impact | Mitigation |
|--------|--------------------|----|-----------|
| **P0 Zeitfenster-Fach-Entscheidung dauert länger** | MEDIUM | MEDIUM | Vorbereitete Kategorisierung, klare Optionen, Decision-Meeting zeitig ansetzen |
| **P1 Confidence-Implementierung komplexer als geschätzt** | MEDIUM | HIGH | Pattern aus nutrition_avg wiederverwenden, Senior Dev assignen |
| **Breaking Changes durch Zeitfenster-Fixes** | LOW | HIGH | Code ist autoritativ, Docs passen sich an → kein Breaking Change |
| **Prompt-Autoren akzeptieren Deprecations nicht** | LOW | MEDIUM | Klare Communication, Replacement-Guides, Grace Period (3 Monate) |
---
## KOMMUNIKATIONS-PLAN
### Week 1 (P0 Kickoff)
- **Email:** Alle Stakeholder über Audit-Ergebnisse informieren
- **Meeting:** P0-Prioritäten mit Tech Lead abstimmen
- **Kickoff:** Development Team P0-Tasks zuweisen
### Week 2 (P1 Kickoff)
- **Standup:** Daily Updates zu Confidence-Implementierung
- **Review:** Mid-Sprint Review nach P1.1-P1.3
### Week 3 (P1 Abschluss)
- **Demo:** P1-Ergebnisse dem Team zeigen
- **Docs:** Updated Catalog veröffentlichen
### Week 4-5 (P2)
- **Meeting:** Production-Readiness-Review
- **Communication:** Deprecation-Plan an Prompt-Autoren
### Week 6 (Abschluss)
- **Retrospektive:** Lessons Learned
- **Documentation:** Finale Compliance-Metrics veröffentlichen
---
## TOOLING & AUTOMATION
### Skripte (entwickeln während P0-P1)
1. `fix_time_window_from_name.py` - Automatische Name-Pattern-Fixes
2. `extract_code_parameters.py` - Code-Parameter → time_window
3. `bulk_update_catalog.py` - JSON-Merge für Bulk-Updates
4. `validate_compliance.py` - Automatische Compliance-Checks
5. `check_production_ready.py` - Production-Eligibility-Check
### CI/CD-Integration (P2-P3)
- Pre-Commit-Hook: Validate neue Platzhalter gegen Normative Spec
- CI: Consistency-Checks (Code ↔ Catalog)
- CD: Automated Catalog-Deployment
---
## ABSCHLUSS-KRITERIEN
**P0 erfolgreich wenn:**
- Alle 3 Code-Docs-Konflikte gelöst
- Alle 74 time_window: unknown → definiert
- Alle 49 No description → vollständig
- Automated Tests grün
**P1 erfolgreich wenn:**
- Mindestens 20 Platzhalter mit Confidence-Logik
- Alle 100 data_layer_module gesetzt
- Alle 90 source_tables gesetzt
- Structured Missing-Value für alle 110 (Dual-Mode)
**P2 erfolgreich wenn:**
- Mindestens 12 Platzhalter `schema_status: production`
- Mindestens 15 Platzhalter `deprecated: true`
- Decision-Log veröffentlicht
**Gesamt-Projekt erfolgreich wenn:**
- **Compliance >= 65%**
- **0 Code-Docs-Konflikte**
- **0 time_window: unknown**
- **12+ Production-Ready Platzhalter**
---
**Maßnahmenplan erstellt von:** Claude Code (Lead Audit Agent)
**Basis:** Gap-Cluster-Analyse, 4-Agent-Evidence
**Genehmigung:** Pending (Review mit Tech Lead + Product Manager)
@@ -0,0 +1,459 @@
# Offene Entscheidungen: Placeholder-Audit
**Audit-Datum:** 29. März 2026
**Status:** Pending Product/Tech Review
**Entscheidungsträger:** Product Manager + Tech Lead
---
## ENTSCHEIDUNGSPFLICHTIGE PUNKTE
Diese Punkte können nicht rein aus Code und Fachlogik gelöst werden und benötigen eine **Produkt-/Fachentscheidung**.
---
## KATEGORIE 1: Zeitfenster-Klassifizierung (BLOCKING P0)
### E1.1: Scores - Zeitfenster definieren
**Betroffene Platzhalter:** 6
- `activity_score`
- `nutrition_score`
- `recovery_score`
- `body_progress_score`
- `goal_progress_score`
- `data_quality_score`
**Problem:**
Scores kombinieren verschiedene Zeitfenster-Metriken. Welches Zeitfenster soll dokumentiert werden?
**Optionen:**
| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: `custom`** | Scores haben keinen festen Zeitrahmen | Technisch korrekt | Unspezifisch für User |
| **B: `mixed`** | Scores kombinieren verschiedene Zeitfenster explizit | Kommuniziert Komplexität | Ähnlich unklar wie `custom` |
| **C: Dominantes Zeitfenster** | Z.B. `28d` für nutrition_score (da Hauptkomponenten 28d) | Einfach zu verstehen | Vereinfachung, evtl. irreführend |
| **D: Zeitfenster pro Sub-Score dokumentieren** | Semantic Contract listet alle Sub-Zeitfenster | Vollständig transparent | Komplex für einfache Use-Cases |
**Empfehlung Audit-Agent:**
- **Option D** für `semantic_contract` (vollständige Transparenz)
- **Option B** für `time_window` Metadatum (signalisiert Komplexität)
**Beispiel (nutrition_score):**
```json
{
"key": "nutrition_score",
"time_window": "mixed",
"semantic_contract": "Composite Score aus: energy_balance (7d), protein_adequacy (28d), macro_consistency (28d). Gewichtung: 40%/40%/20%"
}
```
**Entscheidung benötigt bis:** P0 Week 1 (Zeitfenster-Klassifizierung)
**Impact:** MEDIUM (betrifft Prompt-Interpretation)
**Entscheider:** Product Manager
---
### E1.2: Ability Balance - Zeitfenster definieren
**Betroffene Platzhalter:** 5
- `ability_balance_coordination`
- `ability_balance_endurance`
- `ability_balance_mental`
- `ability_balance_mobility`
- `ability_balance_strength`
**Problem:**
Code implementiert noch keine Ability Balance-Berechnung. Welches Zeitfenster ist fachlich sinnvoll?
**Optionen:**
| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: `28d`** | Rolling-Window über 28 Tage | Konsistent mit anderen Trend-Metriken | Evtl. zu lang für Balance-Shifts |
| **B: `14d`** | Rolling-Window über 14 Tage | Schnellere Reaktion auf Training-Changes | Weniger stabil bei Lücken |
| **C: `latest`** | Snapshot der aktuellen Balance | Einfach | Keine Trend-Info |
**Empfehlung Audit-Agent:**
- **Option A (`28d`)** - Konsistent mit body_metrics, ausreichend stabil
**Rationale:**
- Ability Balance = Verteilung der Trainings-Last über Fähigkeiten
- 28 Tage = ~4 Wochen = typischer Mikrozyklus
- Matching mit anderen Tracking-Metriken
**Entscheidung benötigt bis:** P0 Week 1
**Impact:** MEDIUM (betrifft zukünftige Implementierung)
**Entscheider:** Product Manager + Training-Experte
---
### E1.3: Correlations - Zeitfenster definieren
**Betroffene Platzhalter:** 5
- `correlation_energy_weight_lag`
- `correlation_load_hrv`
- `correlation_load_rhr`
- `correlation_protein_lbm`
- `correlation_sleep_recovery`
**Problem:**
Korrelationen brauchen Mindestdaten. Welches Zeitfenster ist statistisch sinnvoll?
**Optionen:**
| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: `28d`** | Min 21-28 Paare für Reliability | Statistisch robust | Reagiert langsam auf Änderungen |
| **B: `custom`** | Variabel je nach Datenverfügbarkeit | Flexibel | Unklar für User |
| **C: Im Semantic Contract spezifizieren** | Z.B. "28d min, 90d ideal" | Transparent | Komplex |
**Empfehlung Audit-Agent:**
- **Option A (`28d`)** für `time_window`
- **Option C** zusätzlich in `semantic_contract`
**Beispiel:**
```json
{
"key": "correlation_energy_weight_lag",
"time_window": "28d",
"semantic_contract": "Lag-Korrelation (0d/3d/7d/14d) zwischen Energiebilanz und Gewicht. Min 21 Paare (28d) für Reliability, 90d ideal. Explorativ, nicht kausal."
}
```
**Entscheidung benötigt bis:** P0 Week 1
**Impact:** MEDIUM (betrifft Statistik-Interpretation)
**Entscheider:** Tech Lead (Statistik-Know-how)
---
### E1.4: Goals & Focus - Zeitfenster definieren
**Betroffene Platzhalter:** 16
- `active_goals_json`, `active_goals_md`
- `focus_areas_weighted_json`, `focus_areas_weighted_md`, `focus_area_weights_json`
- `top_goal_name`, `top_goal_progress_pct`, `top_goal_status`
- `top_3_goals_behind_schedule`, `top_3_goals_on_track`, `top_3_focus_areas`
- `focus_cat_körper_progress`, `focus_cat_ernährung_progress`, `focus_cat_aktivität_progress`, `focus_cat_recovery_progress`, `focus_cat_vitalwerte_progress`, `focus_cat_mental_progress`, `focus_cat_lebensstil_progress` (jeweils + weight)
**Problem:**
Goals sind Snapshots, aber Progress wird über Zeit berechnet. Wie klassifizieren?
**Optionen:**
| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: `latest`** | Aktueller Stand der Goals | Technisch korrekt (Snapshot) | Impliziert keine Zeit-Dimension |
| **B: `custom`** | Progress-Berechnung ist zeitabhängig | Signalisiert Komplexität | Unklar für Snapshot-Werte |
| **C: Differenzierung** | `active_goals_json`: `latest`, Progress-Felder: `custom` | Präzise | 16 individuelle Entscheidungen |
**Empfehlung Audit-Agent:**
- **Option C** (Differenzierung):
- **Snapshot-Platzhalter** (active_goals_json, focus_area_weights_json, top_goal_name): `latest`
- **Progress-Platzhalter** (top_goal_progress_pct, focus_cat_*_progress): `custom` (da verschiedene Ziele verschiedene Zeiträume haben)
**Entscheidung benötigt bis:** P0 Week 1
**Impact:** LOW (primär dokumentarisch)
**Entscheider:** Product Manager
---
### E1.5: Snapshots - Zeitfenster definieren
**Betroffene Platzhalter:** 7
- `bmi`
- `goal_weight`, `goal_bf_pct`
- `waist_hip_ratio`
- `recomposition_quadrant`
- `plateau_detected`
- `top_drivers`
**Problem:**
Einige sind echte Snapshots (bmi, goal_weight), andere berechnete Werte über Zeit (recomposition_quadrant, plateau_detected).
**Optionen:**
| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| **A: Alle `latest`** | Vereinfachung | Einfach | Ungenau für berechnete |
| **B: Differenzierung** | bmi/goal_weight: `latest`, recomposition_quadrant/plateau_detected: `28d` | Präzise | 7 individuelle Entscheidungen |
**Empfehlung Audit-Agent:**
- **Option B**:
- **Echte Snapshots** (bmi, goal_weight, goal_bf_pct, waist_hip_ratio): `latest`
- **Berechnete über Zeit** (recomposition_quadrant, plateau_detected, top_drivers): `28d` oder `custom`
**Entscheidung benötigt bis:** P0 Week 1
**Impact:** LOW
**Entscheider:** Tech Lead
---
## KATEGORIE 2: Integration ungenutzter Platzhalter (P2)
### E2.1: Ungenutzte Platzhalter - Roadmap-Priorisierung und Integration-Timeline
**Betroffene Platzhalter:** 67 (ungenutzt)
**Kontext:**
67 Platzhalter (60%) haben 0 Verwendungen. **WICHTIG:** Dies ist kein Deprecation-Bedarf, sondern Integration-Planung.
**Fachliche Klassifizierung (siehe USAGE_ROLE_CLASSIFICATION.md):**
- **30 Platzhalter (45%):** Explizit in Roadmap Phase 0c/1/2 geplant
- **37 Platzhalter (55%):** Fachlich plausibel, noch nicht in Prompts integriert
- **0 Platzhalter:** Redundant oder deprecation-würdig
**Neue Fragestellung:**
Nicht "Behalten oder Deprecaten?", sondern "WANN und WIE integrieren?"
---
**Sub-Entscheidungen:**
#### E2.1.1: Geplante Platzhalter (30) - Integration-Timeline bestätigen
**Platzhalter-Gruppen:**
- **Scores (6):** activity_score, nutrition_score, recovery_score, body_progress_score, goal_progress_score, data_quality_score
- **Roadmap:** Phase 0c (Multi-Layer Architecture) + Phase 1 (Charts)
- **Correlations (5):** energy_weight_lag, load_hrv, load_rhr, protein_lbm, sleep_recovery
- **Roadmap:** Phase 2 (Engagement - Korrelationen)
- **Ability Balance (5):** coordination, endurance, mental, mobility, strength
- **Roadmap:** Phase 1 (Charts - Training Balance)
- **Goals Details (11):** active_goals_json/md, focus_areas_weighted, top_3_goals_*, focus_cat_*_progress
- **Roadmap:** Phase 0b/0c (Backend DONE, Prompt-Integration ausstehend)
- **Sleep/Plateau/Drivers (3):** sleep_debt, plateau_detected, top_drivers
- **Roadmap:** Phase 1/2 (Diagnostics)
**Frage:** Timeline bestätigen oder anpassen?
**Optionen:**
- **A: Roadmap wie geplant** - Phase 0c/1/2 (nächste 6-12 Wochen)
- **B: Priorisierung anpassen** - Quick Wins zuerst (z.B. Goals Details sofort)
- **C: Prototyping** - 5-10 Beispiel-Prompts erstellen (Wert demonstrieren)
**Empfehlung:** C → B → A (Prototyping zeigt Wert, dann Priorisierung, dann Roadmap)
---
#### E2.1.2: Plausible Platzhalter (37) - Prompt-Use-Cases identifizieren
**Platzhalter-Gruppen:**
- **Body Deltas (5):** arm_28d_delta, chest_28d_delta, hip_28d_delta, thigh_28d_delta, waist_28d_delta
- **Nutrition Details (6):** energy_deficit_surplus, intake_volatility, nutrition_days, protein_days_in_target, protein_ziel_low/high
- **Training Quality/Load (3):** monotony_score, strain_score, rest_day_compliance
- **Focus Category Weights/Progress (14):** focus_cat_*_weight, focus_cat_*_progress
- **Meta/Convenience (9):** bmi, waist_hip_ratio, datum_heute, zeitraum_*
**Frage:** Für welche Use-Cases Prompt-Templates erstellen?
**Optionen:**
- **A: Alle 37 dokumentieren** - Vollständig, aber aufwändig
- **B: Quick Wins (10-15)** - Offensichtliche Use-Cases zuerst
- **C: Warten bis Bedarf** - Nur auf Anfrage aktivieren
**Empfehlung:** B (10-15 Quick Wins: Body Deltas für Fortschritts-Prompts, Nutrition Details für Coaching-Prompts, Focus Category für Dashboard-Widgets)
---
**Entscheidung benötigt bis:** P2 Week 4
**Impact:** MEDIUM (Prompt-Bibliothek Vollständigkeit)
**Entscheider:** Product Manager + Tech Lead
**Methode:** Integration-Planungs-Meeting (4-6h, siehe Maßnahmenplan P2.2 REVIDIERT)
---
## KATEGORIE 3: Production-Readiness-Kriterien (P2)
### E3.1: Welche Platzhalter sind Production-Ready?
**Problem:**
Aktuell haben alle 111 `schema_status: draft`. Welche Kriterien für `production`?
**Vorgeschlagene Kriterien (aus Maßnahmenplan):**
1. `metadata_completeness_score >= 80`
2. `used_by.prompts.length >= 1 OR used_by.pipelines.length >= 1`
3. `time_window != 'unknown'`
4. `category != 'Unknown'`
5. `description != 'No description available'`
6. `confidence_logic != null OR (type == 'atomic' AND time_window == 'latest')`
7. `known_issues.length == 0`
**Frage:** Sind diese Kriterien zu streng/zu locker?
**Optionen:**
- **A: Wie vorgeschlagen** - Balanced
- **B: Strengere Kriterien** - Z.B. `used_by >= 3`, `completeness_score >= 90`
- **C: Lockerere Kriterien** - Z.B. `completeness_score >= 60`, keine Usage-Requirement
**Empfehlung:** A (wie vorgeschlagen)
**Zusatzfrage:** Soll es Zwischen-Status geben (`beta`, `stable`)?
**Optionen:**
- **A: Nur draft/production** - Einfach
- **B: draft/beta/stable/production** - Differenzierter
**Empfehlung:** B (mehr Nuancen ermöglichen schrittweise Freigabe)
**Entscheidung benötigt bis:** P2 Week 4
**Impact:** MEDIUM (Governance)
**Entscheider:** Tech Lead + Product Manager
---
## KATEGORIE 4: Neue Platzhalter (FUTURE)
### E4.1: Requirements Dev vs. Extended Catalog - Wie priorisieren?
**Problem:**
- **requirements_dev.md** schlägt 27 neue Platzhalter vor (P1-P27)
- **Extended Catalog** hat bereits 111
- Viele der "neuen" sind evtl. schon abgedeckt
**Frage:** Sollen die 27 P1-P27 implementiert werden, oder sind sie durch bestehende abgedeckt?
**Beispiele:**
- **P1: `goal_summary_json`** - Abgedeckt durch `active_goals_json` + `active_goals_md`?
- **P2: `focus_area_summary_json`** - Abgedeckt durch `focus_areas_weighted_json`?
- **P5: `domain_availability_json`** - Neu, nicht vorhanden
- **P12: `body_change_summary_json`** - Teilweise durch `caliper_summary`, `circ_summary`
**Empfehlung:**
- **Mapping-Exercise:** Neue vs. Bestehende
- **Gap-Analyse:** Welche sind echte Lücken?
- **Priorisierung:** Nur echte Gaps implementieren
**Entscheidung benötigt bis:** Nach P2 (Phase 1b Planning)
**Impact:** HIGH (Feature-Roadmap)
**Entscheider:** Product Manager + Tech Lead
---
## KATEGORIE 5: Governance-Prozesse (POST-AUDIT)
### E5.1: Wie werden neue Platzhalter künftig validiert?
**Problem:**
Aktuell gibt es keine systematische Validierung neuer Platzhalter gegen Normative Spec.
**Frage:** Soll ein Pre-Commit-Hook/CI-Check eingeführt werden?
**Optionen:**
- **A: Manuelle Reviews** - Flexibel, aber fehleranfällig
- **B: Automated Checks** - Robust, aber Aufwand für Setup
- **C: Hybrid** - Automated Checks + manuelle Review für komplexe Fälle
**Empfehlung:** C (Hybrid)
**Entscheidung benötigt bis:** Nach P2 (Tooling-Phase)
**Impact:** HIGH (langfristige Qualität)
**Entscheider:** Tech Lead
---
### E5.2: Wer ist Owner für Placeholder-Governance?
**Problem:**
Aktuell kein klarer Owner für Placeholder-Lifecycle.
**Frage:** Soll es eine dedizierte Rolle geben?
**Optionen:**
- **A: Tech Lead** - Technische Verantwortung
- **B: Product Manager** - Fachliche Verantwortung
- **C: Shared (beide)** - Consensus-basiert
- **D: Dedizierte Rolle "Data-Contract-Owner"** - Spezialisiert
**Empfehlung:** C (Shared) für jetzt, D langfristig
**Entscheidung benötigt bis:** Nach P2
**Impact:** MEDIUM (Governance)
**Entscheider:** Management
---
## KATEGORIE 6: Technische Schulden (POST-P2)
### E6.1: Legacy-String "nicht verfügbar" - Wann abschalten?
**Problem:**
P1.6 führt Dual-Mode ein (Legacy + Structured). Wann soll Legacy deprecated werden?
**Optionen:**
- **A: Nach 3 Monaten** - Schnell
- **B: Nach 6 Monaten** - Standard
- **C: Nach 12 Monaten** - Konservativ
- **D: Nie (dauerhaft Dual-Mode)** - Ewig Backward-Compatible
**Empfehlung:** B (6 Monate) mit klarer Migration-Guidance
**Entscheidung benötigt bis:** P1 Abschluss (Sunset-Datum festlegen)
**Impact:** MEDIUM (Breaking Change für Prompts)
**Entscheider:** Tech Lead + Prompt-Autoren
---
## ZUSAMMENFASSUNG OFFENER ENTSCHEIDUNGEN
| ID | Kategorie | Entscheidung | Dringlichkeit | Entscheider |
|----|-----------|--------------|---------------|-------------|
| **E1.1** | Zeitfenster Scores | custom/mixed/dominant? | 🔴 P0 Week 1 | Product |
| **E1.2** | Zeitfenster Ability Balance | 28d/14d/latest? | 🔴 P0 Week 1 | Product + Training-Expert |
| **E1.3** | Zeitfenster Correlations | 28d mit Min-Data? | 🔴 P0 Week 1 | Tech Lead |
| **E1.4** | Zeitfenster Goals & Focus | latest/custom/differenziert? | 🔴 P0 Week 1 | Product |
| **E1.5** | Zeitfenster Snapshots | latest/differenziert? | 🔴 P0 Week 1 | Tech Lead |
| **E2.1** | Integration-Timeline | 67 ungenutzte integrieren | 🟡 P2 Week 4 | Product |
| **E3.1** | Production-Kriterien | draft/beta/stable/production? | 🟡 P2 Week 4 | Tech + Product |
| **E4.1** | Neue Platzhalter P1-P27 | Welche implementieren? | 🟢 Post-P2 | Product |
| **E5.1** | Validierungs-Prozess | Automated/Manual/Hybrid? | 🟢 Post-P2 | Tech Lead |
| **E5.2** | Governance-Owner | Wer verantwortet Placeholders? | 🟢 Post-P2 | Management |
| **E6.1** | Legacy-Sunset | Wann "nicht verfügbar" abschalten? | 🟡 P1 Abschluss | Tech Lead |
**Legende:**
- 🔴 BLOCKING (P0) - Entscheidung innerhalb Week 1 benötigt
- 🟡 HIGH (P1-P2) - Entscheidung innerhalb Week 4-5 benötigt
- 🟢 MEDIUM (Post-P2) - Kann warten
---
## EMPFOHLENER ENTSCHEIDUNGS-PROZESS
### Week 1 (P0 Kickoff)
1. **Meeting (2h):** Product + Tech Lead + Training-Expert
2. **Agenda:**
- E1.1-E1.5: Alle Zeitfenster-Entscheidungen
- Decision-Log erstellen
3. **Output:** Entschiedene Zeitfenster für alle 39 unkla
ren Platzhalter
### Week 4 (P2)
1. **Meeting (2h):** Product + Tech Lead
2. **Agenda:**
- E2.1: Deprecation-Review (67 ungenutzte)
- E3.1: Production-Kriterien
3. **Output:** Deprecation-Liste, Production-Kriterien finalisiert
### Post-P2
1. **Meeting (1h):** Management + Tech + Product
2. **Agenda:**
- E4.1: Neue Platzhalter-Roadmap
- E5.1-E5.2: Governance-Prozesse
- E6.1: Legacy-Sunset-Datum
3. **Output:** Langfristige Placeholder-Governance etabliert
---
## NÄCHSTE SCHRITTE
1. **Dieses Dokument reviewen** mit Product Manager
2. **P0-Meeting ansetzen** (Week 1) für Zeitfenster-Entscheidungen
3. **Decision-Log starten** (Living Document)
4. **Nach Entscheidungen:** Maßnahmenplan P0 final anpassen
---
**Offene Entscheidungen dokumentiert von:** Claude Code (Lead Audit Agent)
**Review benötigt von:** Product Manager + Tech Lead
**Deadline kritische Entscheidungen:** P0 Week 1 (innerhalb 1 Woche)
@@ -0,0 +1,351 @@
# Quellenprotokoll: Placeholder-Audit
**Audit-Datum:** 29. März 2026
**Audit-Dauer:** ~590 Sekunden (4 Agents parallel)
**Methodik:** 4 spezialisierte Agents mit Cross-Validation
---
## 1. GELESENE DATEIEN
### 1.1 Normative und Spezifikations-Dokumente (HÖCHSTE PRIORITÄT)
| Datei | Pfad | Zeilen | Priorität | Nutzung | Authoritative |
|-------|------|--------|-----------|---------|---------------|
| **NORMATIVE.md** | `.claude/docs/audit/platzhalter/PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md` | 387 | 1 (Höchste) | Verbindliche Standardspezifikation, alle Norm-Referenzen | ✅ JA |
| **EXPORT_SPEC.md** | `.claude/docs/audit/platzhalter/PLACEHOLDER_EXPORT_SPEC.md` | 24 | 2 | API-Endpoint-Spezifikation, Export-Struktur | ✅ JA |
| **GAP_REPORT.md** | `.claude/docs/audit/platzhalter/PLACEHOLDER_GAP_REPORT.md` | 67+ | 3 | Initial Gap-Zahlen (74 unknown, 100 data_layer fehlt) | ⚠️ TEILWEISE |
| **CATALOG.json** | `.claude/docs/audit/platzhalter/PLACEHOLDER_CATALOG_EXTENDED.json` | 64817 Tokens | 4 | Ist-Zustand alle 111 Platzhalter (vollständig) | ✅ JA |
| **CATALOG.md** | `.claude/docs/audit/platzhalter/PLACEHOLDER_CATALOG_EXTENDED.md` | 148+ | 4 | Human-readable Catalog (Kategorien, Übersicht) | ⚠️ TEILWEISE |
---
### 1.2 Fachliche Dokumentation
| Datei | Pfad | Zeilen | Nutzung | Authoritative |
|-------|------|--------|---------|---------------|
| **DATA_ARCHITECTURE.md** | `.claude/docs/audit/platzhalter/DATA_ARCHITECTURE.md` | 300+ (Teil) | Fachliche Datenarchitektur, Domänen-Entitäten, Berechnungslogiken | ⚠️ FACHLICH |
| **requirements_dev.md** | `.claude/docs/audit/platzhalter/placeholder_requirements_for_development.md` | 704 | Entwickler-Arbeitsdokument, P1-P27 neue Platzhalter-Vorschläge | ❌ NICHT normativ |
| **konzept_v2.md** | `.claude/docs/audit/platzhalter/mitai_jinkendo_konzept_diagramme_auswertungen_v2.md` | 2086 | Chart-Spezifikationen (K1-K5, E1-E5, A1-A8, C1-C7, S1-S3) | ⚠️ FACHLICH |
---
### 1.3 Code-Dateien (Code-Evidence-Agent)
| Datei | Pfad | Zeilen | Nutzung | Authoritative |
|-------|------|--------|---------|---------------|
| **placeholder_resolver.py** | `backend/placeholder_resolver.py` | ~1300 | PLACEHOLDER_MAP (Zeilen 1075-1221), Helper-Funktionen (_safe_*) | ✅ JA (Code) |
| **body_metrics.py** | `backend/data_layer/body_metrics.py` | 831 | Weight, BF%, Circumferences, Trends, Deltas | ✅ JA (Code) |
| **nutrition_metrics.py** | `backend/data_layer/nutrition_metrics.py` | 1093 | Nutrition Averages, Energy Balance, Protein Adequacy | ✅ JA (Code) |
| **activity_metrics.py** | `backend/data_layer/activity_metrics.py` | 906 | Training Volume, Quality, Load Monitoring, Ability Balance | ✅ JA (Code) |
| **recovery_metrics.py** | `backend/data_layer/recovery_metrics.py` | 879 | Sleep Metrics, HRV/RHR Baselines, Recovery Scoring | ✅ JA (Code) |
| **scores.py** | `backend/data_layer/scores.py` | 584 | Focus Weights, Goal Progress, Category Scores | ✅ JA (Code) |
| **correlations.py** | `backend/data_layer/correlations.py` | 504 | Lag Correlations, Plateau Detection, Top Drivers | ✅ JA (Code) |
| **prompts.py (Router)** | `backend/routers/prompts.py` | ~2246 | Export-Endpoints (Zeilen 370-467: extended export) | ✅ JA (Code) |
| **goal_utils.py** | `backend/goal_utils.py` | Teilweise | Goal-Helper-Funktionen | ✅ JA (Code) |
---
### 1.4 Zusätzliche Projektdokumente
| Datei | Pfad | Nutzung | Authoritative |
|-------|------|---------|---------------|
| **CLAUDE.md** | `.claude/CLAUDE.md` | Projekt-Kontext, Tech-Stack, Versions-Historie | ⚠️ KONTEXT |
| **ARCHITECTURE.md** | `.claude/rules/ARCHITECTURE.md` | Architektur-Regeln, Versionskontrolle | ⚠️ KONTEXT |
| **CODING_RULES.md** | `.claude/rules/CODING_RULES.md` | Coding-Standards | ⚠️ KONTEXT |
| **LESSONS_LEARNED.md** | `.claude/rules/LESSONS_LEARNED.md` | Bekannte Fehler-Patterns | ⚠️ KONTEXT |
---
## 2. RANGFOLGE DER QUELLEN (BEI KONFLIKTEN)
Bei Widersprüchen zwischen Quellen gilt folgende Priorität:
| Rang | Quelle | Regel | Beispiel-Konflikt |
|------|--------|-------|-------------------|
| **1** | **Normative Spec** | Verbindliche Standardspezifikation | time_window-Werte: Nur latest/7d/14d/28d/30d/90d/custom/mixed/unknown erlaubt |
| **2** | **Code (Ist-Zustand)** | Bei Konflikt Docs vs. Code → Code ist autoritativ | `weight_trend`: Docs "7d/30d", Code 28d → **Code gewinnt** |
| **3** | **Extended Catalog** | Generated Truth (Ist-Zustand dokumentiert) | Bestandszahlen: 111 Platzhalter |
| **4** | **Export Spec / Gap Report** | Technische Spezifikation/Diagnose | Export-Format, Gap-Zahlen |
| **5** | **DATA_ARCHITECTURE.md** | Fachliche Referenz | Semantic Contracts, Berechnungslogiken |
| **6** | **konzept_v2.md** | Chart-/Feature-Spezifikationen | Diagramm-Anforderungen |
| **7** | **requirements_dev.md** | **NICHT NORMATIV** - Arbeitsdokument | P1-P27 Vorschläge (nicht bindend) |
| **8** | **Projekt-Context** | Hintergrund-Information | CLAUDE.md, ARCHITECTURE.md |
**Wichtig:** `requirements_dev.md` ist **KEIN normativer Standard**, sondern ein Entwickler-Arbeitsdokument für Planung!
---
## 3. MAẞGEBLICHE AUSSAGEN PRO QUELLE
### 3.1 NORMATIVE.md (Verbindliche Standard-Instanz)
**Maßgebliche Aussagen:**
- §3.4: **"Zeitfenster explizit"** → Pflicht für alle Platzhalter
- §3.5: **"Fehlwerte explizit"** → Strukturierte Felder statt nur String
- §5: **"Qualitäts-/Confidence-Logik"** → Confidence für Trends/Scores
- §7.1: **Pflichtfelder:** key, placeholder, category, type, description, semantic_contract, unit, time_window, output_type, value_display, available, missing_value_policy, source, version, deprecated
- §7.2-7.4: **Erlaubte Werte** für type, time_window, output_type
**Verwendung im Audit:**
- Compliance-Bewertung (compliant/partially_compliant/non_compliant)
- Gap-Identifikation (Verstoß gegen §X)
- Remediation-Priorisierung (Norm-Verstöße = P0)
---
### 3.2 Code (placeholder_resolver.py + data_layer/*)
**Maßgebliche Aussagen:**
- **Zeitfenster im Code:**
- `weight_trend`: `days=28` (Zeile ~1084)
- `activity_summary`: `days=14` (Zeile ~1102)
- `sleep_avg_duration`: `days=7` (Zeile ~1107)
- **Resolver-Mappings:** 111 Platzhalter vollständig implementiert (Zeilen 1075-1221)
- **Helper-Funktionen:** `_safe_int`, `_safe_float`, `_safe_str`, `_safe_json` (Zeilen 406-602)
- **Data-Layer-Calls:** Code-Evidence-Agent hat vollständige Traces
- **Confidence-Logik:** Nur in nutrition_metrics, body_metrics, activity_metrics implementiert
**Verwendung im Audit:**
- **Autoritativ bei Konflikten** (Code > Docs)
- Technische Herkunft (data_layer_module, source_tables)
- Zeitfenster-Extraktion (Default-Parameter)
---
### 3.3 Extended Catalog (PLACEHOLDER_CATALOG_EXTENDED.json)
**Maßgebliche Aussagen:**
- **111 Platzhalter** (vollständiger Bestand)
- **Kategorien-Verteilung:**
- 49 Unknown (44%)
- 11 Körper, 9 Training, 8 Ernährung, 8 Focus Areas, 7 Schlaf/Erholung, 6 Vitalwerte, 6 Scores, 4 Profil, 3 Zeitraum
- **time_window: unknown:** 74 (67%)
- **metadata_completeness_score: 0** für alle 111
- **schema_status: draft** für alle 111
**Verwendung im Audit:**
- Bestandsaufnahme (Was existiert?)
- Ist-Zustand-Baseline
- Gap-Zahlen-Validierung
---
### 3.4 DATA_ARCHITECTURE.md (Fachliche Ableitung)
**Maßgebliche Aussagen:**
- **Domänen-Struktur:** Nutzer & Zielsetzung, Körper, Training, Lifestyle, Auswertungen
- **Berechnungslogiken:**
- BMI = weight / (height_m ^ 2)
- Protein-Ziel = weight × 1.6-2.2 g/kg
- Energy-Balance = intake - (TDEE + training_kcal)
- **Zeitfenster-Heuristiken:**
- Trends: 7d/28d/90d
- Scores: mixed (verschiedene Sub-Komponenten)
- Correlations: 28d (Min-Daten für Reliability)
**Verwendung im Audit:**
- Semantic Contracts ableiten (wo Code unklar)
- Fachliche Kategorien bestimmen
- Zeitfenster-Empfehlungen (bei Code-Unklarheit)
---
### 3.5 requirements_dev.md (NICHT AUTORITATIV)
**Status:** Arbeitsdokument, **KEINE** normative Instanz
**Maßgebliche Aussagen (mit Vorsicht):**
- Vorschläge für 27 neue Platzhalter (P1-P27)
- Governance-Regeln (G1-G7) - **sollten** in Normative Spec überführt werden
**Verwendung im Audit:**
- **Referenz für geplante Features** (nicht für Ist-Zustand)
- **Konflikte mit Extended Catalog:** requirements_dev ist NICHT autoritativ
- Beispiel-Konflikt: requirements_dev nennt P1 `goal_summary_json` als "neu nötig", aber Extended Catalog hat bereits `active_goals_json` → **Catalog gewinnt**
---
## 4. WIDERSPRÜCHE ZWISCHEN QUELLEN
### 4.1 Dokumentierte Konflikte
| Konflikt | Quelle 1 | Quelle 2 | Resolution | Audit-Entscheidung |
|----------|----------|----------|------------|---------------------|
| **weight_trend Zeitfenster** | Description: "7d/30d" | Code: 28d | Code gewinnt (Rang 2 > Rang 5) | Code ist autoritativ → Docs aktualisieren |
| **activity_summary Zeitfenster** | Description: "7d" | Code: 14d | Code gewinnt | Code ist autoritativ → Docs aktualisieren |
| **Bestandszahlen** | Export Spec: 116 | Extended Catalog: 111 | 5 Metafelder (Rang 3 > Rang 4) | 111 User-Placeholders + 5 Meta |
| **Neue Platzhalter** | requirements_dev: P1-P27 "neu" | Extended Catalog: 111 existierend | Catalog ist Truth (Rang 3 > Rang 7) | requirements_dev ist Planning, nicht Ist-Zustand |
---
### 4.2 Inkonsistenzen zwischen Dokumenten
| Dokument A | Aussage A | Dokument B | Aussage B | Audit-Behandlung |
|------------|-----------|------------|-----------|------------------|
| GAP_REPORT.md | "74 unknown time_window" | Code-Evidence | "75 unklar im Code" | Beide korrekt (leichte Differenz durch Fuzzy-Matching) |
| requirements_dev.md | "Ability Balance fehlt" | Extended Catalog | "Ability Balance existiert (5 Platzhalter)" | Extended Catalog gewinnt (existiert, aber ungenutzt) |
| konzept_v2.md | "E1 Energiebilanz Chart braucht X" | Code | "Nicht implementiert" | Konzept ist Soll, Code ist Ist → Kein Konflikt (Feature-Gap) |
---
## 5. FACHLICH ABGELEITETE AUSSAGEN
Diese Aussagen stammen **nicht direkt aus Code**, sondern wurden **fachlich inferiert**:
| Aussage | Quelle | Ableitung | Evidence-Level |
|---------|--------|-----------|----------------|
| **Ability Balance Zeitfenster: 28d** | DATA_ARCHITECTURE 3.2 + Audit-Heuristik | Konsistent mit anderen Trend-Metriken | `fachlich_abgeleitet` |
| **Correlations Zeitfenster: 28d** | konzept_v2.md (C1-C7) + Statistik-Heuristik | Min 21-28 Paare für Reliability | `fachlich_abgeleitet` |
| **Scores Zeitfenster: mixed** | DATA_ARCHITECTURE + Code-Analyse | Kombinieren verschiedene Sub-Zeitfenster | `fachlich_abgeleitet` |
| **49 Non-Compliant Semantic Contracts** | Semantic-Contract-Agent + DATA_ARCHITECTURE | Aus Datenarchitektur inferiert | `fachlich_abgeleitet` |
**Wichtig:** Alle fachlich abgeleiteten Aussagen sind im Audit **klar gekennzeichnet** mit `evidence_level: "fachlich_abgeleitet"`.
---
## 6. NICHT VERWENDETE QUELLEN
### 6.1 Bewusst ausgeschlossen
| Quelle | Grund für Ausschluss |
|--------|----------------------|
| **Frontend-Code** | Nicht relevant für Backend-Placeholder-Definitionen |
| **Prompt-Templates in DB** | Verwendung wird aus Catalog-Metadaten (`used_by`) extrahiert |
| **Alte Dokumentationen** | Legacy, nicht mehr aktuell |
| **Git History** | Nicht relevant für Ist-Zustand (Audit fokussiert auf Current State) |
---
### 6.2 Fehlende Quellen (würden Audit verbessern)
| Fehlende Quelle | Warum hilfreich | Impact |
|-----------------|-----------------|--------|
| **Unit-Tests für Platzhalter** | Würden erwartete Outputs dokumentieren | MEDIUM (bessere Semantic Contracts) |
| **Prompt-Library-Dokumentation** | Würde zeigen, welche Platzhalter wie genutzt werden | MEDIUM (bessere Usage-Analyse) |
| **Historical Change-Log** | Würde Breaking Changes dokumentieren | LOW (nur für Deprecation-History) |
| **User-Feedback zu Platzhaltern** | Würde Probleme/Unklarheiten zeigen | LOW (kein Bestand vorhanden) |
---
## 7. AGENT-SPEZIFISCHE QUELLENNUTZUNG
### 7.1 Code-Evidence-Agent (124s)
**Genutzte Quellen:**
1. `placeholder_resolver.py` (vollständig, Zeilen 1-1300)
2. `data_layer/*.py` (alle 6 Module)
3. `routers/prompts.py` (Export-Logik)
4. `goal_utils.py` (Goal-Helper)
**Output:**
- Resolver-Funktionen für alle 111 Platzhalter
- Data-Layer-Module (81 via Helper, 19 direkt)
- Source-Tables (aus SQL-Queries extrahiert)
- Zeitfenster aus Default-Parametern
**Evidence-Level:** `code_verified` (100%)
---
### 7.2 Semantic-Contract-Agent (218s)
**Genutzte Quellen:**
1. `PLACEHOLDER_CATALOG_EXTENDED.json` (Ist-Zustand)
2. `DATA_ARCHITECTURE.md` (Fachliche Bedeutung)
3. `mitai_jinkendo_konzept_diagramme_auswertungen_v2.md` (Chart-Specs)
**Output:**
- Target-Descriptions für alle 49 Non-Compliant
- Target-Categories (Unknown → fachliche Kategorien)
- Semantic Contracts (aus Datenarchitektur abgeleitet)
**Evidence-Level:**
- `documentation_verified` (56% - in Konzeptdokumenten begründet)
- `fachlich_abgeleitet` (44% - aus Datenarchitektur inferiert)
---
### 7.3 Time-Window-Confidence-Agent (90s)
**Genutzte Quellen:**
1. `PLACEHOLDER_CATALOG_EXTENDED.json` (Ist-Zustand time_window)
2. `placeholder_resolver.py` + `data_layer/*.py` (Code-Parameter)
3. `PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md` (Erlaubte Werte)
**Output:**
- Zeitfenster-Status für alle 111 (74 unknown, 37 definiert)
- Aggregationslogik (mean, median, slope, etc.)
- Confidence-Logik-Status (8 haben, 103 fehlt)
- Min-Data-Thresholds (wo identifizierbar)
**Evidence-Level:**
- `code_verified` (Zeitfenster aus Code: 37)
- `code_inferred` (75 unklar im Code, fachlich geschätzt)
---
### 7.4 Prompt-Usage-Agent (157s)
**Genutzte Quellen:**
1. `PLACEHOLDER_CATALOG_EXTENDED.json` (`used_by` Metadaten)
2. Grep-Suche nach `{{placeholder_name}}` in Backend (Code-Search)
**Output:**
- Usage-Count für alle 111 (12 kritisch, 32 wichtig, 67 ungenutzt)
- Criticality-Klassifizierung (produktkritisch/wichtig/ungenutzt)
- Rename-Risk-Bewertung (HIGH/MEDIUM/LOW)
**Evidence-Level:** `catalog_verified` (100% aus Extended Catalog)
---
## 8. CROSS-VALIDATION ZWISCHEN AGENTS
**Validierungs-Methodik:**
- Jeder Placeholder wurde von **4 Perspektiven** geprüft
- Konflikte wurden nach Rangfolge aufgelöst (Norm > Code > Catalog > Docs)
- Evidence-Levels dokumentieren Sicherheit der Aussage
**Beispiel-Cross-Validation (weight_trend):**
| Agent | Perspektive | Aussage | Evidence-Level |
|-------|-------------|---------|----------------|
| **Code-Evidence** | Technisch | `days=28` im Code | `code_verified` |
| **Semantic-Contract** | Fachlich | Description sagt "7d/30d" | `documentation_verified` |
| **Time-Window-Confidence** | Zeitfenster | Code 28d vs. Docs 7d/30d → **KONFLIKT** | `code_verified` |
| **Prompt-Usage** | Verwendung | 10 Prompts/Pipelines nutzen es | `catalog_verified` |
| **→ Resolution** | | Code gewinnt → time_window: 28d | `code_verified` |
---
## 9. QUELLENPROTOKOLL-ZUSAMMENFASSUNG
**Gelesene Dateien:** 20+
- **Normative/Spec:** 5 (NORMATIVE.md, EXPORT_SPEC, GAP_REPORT, CATALOG.json, CATALOG.md)
- **Fachlich:** 3 (DATA_ARCHITECTURE, requirements_dev, konzept_v2)
- **Code:** 9+ (placeholder_resolver.py, data_layer/*, routers/prompts.py)
- **Kontext:** 4 (CLAUDE.md, ARCHITECTURE.md, CODING_RULES, LESSONS_LEARNED)
**Maßgebliche Quellen:** 8
- **Rang 1 (Norm):** NORMATIVE.md
- **Rang 2 (Code):** placeholder_resolver.py, data_layer/*
- **Rang 3 (Truth):** PLACEHOLDER_CATALOG_EXTENDED.json
**Konflikte:** 4 dokumentiert, alle nach Rangfolge aufgelöst
**Widersprüche:** 3 dokumentiert
- weight_trend: Code (28d) vs. Docs (7d/30d) → **Code gewinnt**
- activity_summary: Code (14d) vs. Docs (7d) → **Code gewinnt**
- Bestandszahlen: 116 vs. 111 → **111 User-Placeholders + 5 Meta**
**Fachlich abgeleitete Aussagen:** 49 Non-Compliant Semantic Contracts
- **Evidence-Level:** `fachlich_abgeleitet` (klar gekennzeichnet)
**Nicht verwendete Quellen:** Frontend-Code, Prompt-DB, Git History (bewusst ausgeschlossen)
---
**Quellenprotokoll erstellt von:** Claude Code (Lead Audit Agent)
**Audit-Methodik:** 4-Agent-Cross-Validation mit Rangfolgen-basierter Konflikt-Resolution
**Transparenz:** Alle Aussagen mit Evidence-Level dokumentiert (code_verified/documentation_verified/fachlich_abgeleitet/unclear)
@@ -0,0 +1,340 @@
# Normative Prüfmatrix: Summary
**Audit-Datum:** 29. März 2026
**Umfang:** 111 Platzhalter
**Normative Basis:** PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md v1.0.0
---
## HINWEIS ZUR VOLLSTÄNDIGEN MATRIX
Die **vollständige Prüfmatrix** (111 Platzhalter × ~40 Felder = ~4500 Datenpunkte) würde ein extrem großes Dokument ergeben.
Stattdessen:
1. **Dieser Summary** zeigt die kritischsten Findings pro Compliance-Level
2. **Detaillierte Einzelberichte** siehe Agent-Outputs (bereits vorhanden)
3. **Maschinenlesbare Version:** Nutze `PLACEHOLDER_CATALOG_EXTENDED.json` direkt
---
## COMPLIANCE-ÜBERSICHT (111 PLATZHALTER)
### Voll Normkonform (8 Platzhalter - 7%)
| Key | Category | Time-Window | Confidence | Used-By | Why Compliant |
|-----|----------|-------------|------------|---------|---------------|
| `protein_avg` | Ernährung | 30d | ✅ calculate_confidence | 0 | Best-Practice-Modell |
| `kcal_avg` | Ernährung | 30d | ✅ calculate_confidence | 0 | Best-Practice-Modell |
| `fat_avg` | Ernährung | 30d | ✅ calculate_confidence | 0 | Best-Practice-Modell |
| `carb_avg` | Ernährung | 30d | ✅ calculate_confidence | 0 | Best-Practice-Modell |
| `weight_aktuell` | Körper | latest | ✅ high/insufficient | 10 | Latest-Pattern-Modell |
| `weight_trend` | Körper | 28d | ✅ calculate_confidence | 10 | **Code-Konflikt (Docs 7d/30d)** |
| `circ_summary` | Körper | mixed | ✅ high/insufficient | 8 | Best-of-Each-Pattern |
| `age` | Profil | keine | ❌ (not needed) | 2 | Snapshot, no confidence needed |
**Pattern:** Nutrition-Averages + Weight-Aktuell = Best-Practice-Modelle für alle anderen
---
### Partially Compliant (22 Platzhalter - 20%)
**Charakteristik:** 1-2 Gaps, meist time_window oder confidence
| Key | Category | Missing | Priority | Action |
|-----|----------|---------|----------|--------|
| `caliper_summary` | Körper | time_window: unknown | P0 | → latest |
| `kf_aktuell` | Körper | time_window: unknown | P0 | → latest |
| `sleep_avg_duration` | Schlaf & Erholung | time_window: unknown (Code: 7d) | P0 | → 7d |
| `sleep_avg_quality` | Schlaf & Erholung | time_window: unknown (Code: 7d) | P0 | → 7d |
| `rest_days_count` | Schlaf & Erholung | time_window: unknown (Code: 30d) | P0 | → 30d |
| `vitals_avg_hr` | Vitalwerte | time_window: unknown (Code: 7d) | P0 | → 7d |
| `vitals_avg_hrv` | Vitalwerte | time_window: unknown (Code: 7d) | P0 | → 7d |
| `vitals_vo2_max` | Vitalwerte | time_window: unknown, weak semantic_contract | P0 + P1 | → latest + sharpen contract |
| `bmi` | Körper | time_window: unknown, weak semantic_contract | P0 | → latest + Formel dokumentieren |
| ... (13 weitere) | | | | |
**Remediation:** P0 time_window + teilweise P1 semantic_contract sharpening
---
### Non-Compliant (81 Platzhalter - 73%)
**Charakteristik:** 3+ Gaps, meist Unknown category + No description + unknown time_window
#### Cluster 1: Unknown Category + No Description (49)
**Sub-Gruppen:**
**A. Ability Balance (5):**
- `ability_balance_coordination`, `ability_balance_endurance`, `ability_balance_mental`, `ability_balance_mobility`, `ability_balance_strength`
- **Gaps:** category: Unknown, description: No description, time_window: unknown
- **Fix:** category: Training, time_window: 28d, descriptions aus Semantic-Agent-Report
- **Priority:** P0 (Bulk-Update)
**B. Correlations (5):**
- `correlation_energy_weight_lag`, `correlation_load_hrv`, `correlation_load_rhr`, `correlation_protein_lbm`, `correlation_sleep_recovery`
- **Gaps:** category: Unknown, description: No description, time_window: unknown, confidence: null
- **Fix:** category: Auswertung, time_window: 28d, confidence: pair-based, descriptions aus Semantic-Agent
- **Priority:** P0 (description) + P1 (confidence)
**C. Goals & Focus (16):**
- `active_goals_json`, `active_goals_md`, `focus_areas_weighted_json`, `focus_areas_weighted_md`, `focus_area_weights_json`
- `top_goal_name`, `top_goal_progress_pct`, `top_goal_status`
- `top_3_goals_behind_schedule`, `top_3_goals_on_track`, `top_3_focus_areas`
- `focus_cat_körper_progress/weight`, `focus_cat_ernährung_progress/weight`, `focus_cat_aktivität_progress/weight`, `focus_cat_recovery_progress/weight`, `focus_cat_vitalwerte_progress/weight`
- **Gaps:** category: Unknown, description: No description, time_window: unknown
- **Fix:** category: Ziele, time_window: latest (Snapshot) oder custom (Progress), descriptions aus Semantic-Agent
- **Priority:** P0 (Bulk-Update)
**D. Body Deltas (5):**
- `arm_28d_delta`, `chest_28d_delta`, `hip_28d_delta`, `thigh_28d_delta` (waist_28d_delta ist Partially Compliant)
- **Gaps:** category: Unknown, description: No description, time_window: unknown (sollte 28d sein), confidence: null
- **Fix:** category: Körper, time_window: 28d, confidence: delta-confidence, descriptions aus Semantic-Agent
- **Priority:** P0 (description) + P1 (confidence)
**E. Nutrition (6):**
- `energy_deficit_surplus`, `intake_volatility`, `nutrition_days`, `protein_days_in_target`, `protein_ziel_low`, `protein_ziel_high`
- **Gaps:** category: Unknown, description: No description, time_window: unknown
- **Fix:** category: Ernährung, time_window: 7d/28d/30d (je nach Funktion), descriptions aus Semantic-Agent
- **Priority:** P0 (Bulk-Update)
**F. Training (8):**
- `activity_detail`, `activity_summary` (Code-Konflikt!), `trainingstyp_verteilung`, `training_minutes_week`, `training_frequency_7d`
- `quality_sessions_pct`, `monotony_score`, `strain_score`, `rest_day_compliance`, `proxy_internal_load_7d`
- **Gaps:** category: Unknown (teilweise Training), description: No description (teilweise), time_window: unknown
- **Fix:** category: Training, time_window: 7d/14d/28d (aus Code), descriptions aus Semantic-Agent
- **Priority:** P0 (time_window, Code-Konflikte) + P1 (confidence für Scores)
**G. Meta/Sonstiges (4):**
- `zeitraum_90d`, `goal_weight`, `goal_bf_pct`, `weight_90d_slope`, `plateau_detected`, `top_drivers`, etc.
- **Gaps:** Gemischt
- **Fix:** Individuell je Platzhalter
- **Priority:** P0-P1
---
#### Cluster 2: Fehlende Confidence (103 - inkl. Partially Compliant)
**Kritischste:** Trend-Platzhalter (11)
- `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`
**Gap:** confidence_logic: null
**Fix:** Implementiere calculate_confidence(data_points, time_window_days, 'trend')
**Priority:** P1 (12-16h)
---
#### Cluster 3: Fehlende Data-Layer-Module (100)
**Alle außer:**
- nutrition_avg (4), weight_aktuell, weight_trend, kf_aktuell, caliper_summary, circ_summary, age, height, name, geschlecht
**Gap:** data_layer_module: null
**Fix:** Mapping aus Code-Evidence-Agent-Report übernehmen (Bulk-Update)
**Priority:** P1 (6-8h, automatisierbar)
---
#### Cluster 4: Fehlende Source-Tables (90)
**Ähnlich Cluster 3**
**Gap:** source_tables: []
**Fix:** Mapping aus Code-Evidence-Agent-Report übernehmen (Bulk-Update)
**Priority:** P1 (6-8h, automatisierbar)
---
## COMPLIANCE-MATRIX NACH KATEGORIE
| Kategorie | Total | Compliant | Partially | Non-Compliant | Kritischste Gaps |
|-----------|-------|-----------|-----------|---------------|------------------|
| **Ernährung** | 8 | 4 (50%) | 0 | 4 | time_window, description |
| **Körper** | 11 | 3 (27%) | 5 | 3 | time_window, confidence (Trends) |
| **Training** | 9 | 0 | 2 | 7 | category, description, time_window |
| **Profil** | 4 | 1 (25%) | 3 | 0 | time_window (unkritisch) |
| **Schlaf & Erholung** | 7 | 0 | 3 | 4 | time_window, description |
| **Vitalwerte** | 6 | 0 | 3 | 3 | time_window, semantic_contract |
| **Scores (Phase 0b)** | 6 | 0 | 0 | 6 | time_window, confidence |
| **Focus Areas** | 8 | 0 | 0 | 8 | category, description, time_window |
| **Zeitraum** | 3 | 0 | 0 | 3 | time_window (Name-Mismatch!) |
| **Unknown** | 49 | 0 | 6 | 43 | Alles (category, description, time_window, confidence) |
**Auffälligkeiten:**
- **Ernährung:** 50% Compliance dank Best-Practice nutrition_avg
- **Unknown-Kategorie:** 88% Non-Compliant (43/49)
- **Training:** 0% Fully Compliant, aber nur 2 Partially → hoher Remediation-Bedarf
---
## PRODUKTKRITISCHE PLATZHALTER (12)
**Diese 12 haben >3 Verwendungen = Breaking-Change-Risk bei Änderungen**
| Rank | Key | Uses | Category | Compliance | Kritische Gaps | Risk |
|------|-----|------|----------|------------|----------------|------|
| 1 | `name` | 19 | Profil | Partially | time_window (unkritisch) | 🔴 EXTREM |
| 2 | `geschlecht` | 14 | Profil | Partially | time_window (unkritisch) | 🔴 EXTREM |
| 3 | `height` | 12 | Profil | Partially | time_window (unkritisch) | 🔴 EXTREM |
| 4 | `weight_aktuell` | 10 | Körper | ✅ Compliant | Keine | 🔴 HOCH (Format-sensitiv) |
| 5 | `weight_trend` | 10 | Körper | ✅ Compliant | **Code-Docs-Konflikt** | 🔴 HOCH (Code-Fix P0) |
| 6 | `goal_bf_pct` | 10 | Unknown | Non-Compliant | category, description, time_window | 🔴 HOCH |
| 7 | `caliper_summary` | 8 | Körper | Partially | time_window | 🟡 MITTEL |
| 8 | `circ_summary` | 8 | Körper | ✅ Compliant | Keine | 🟡 MITTEL |
| 9 | `goal_weight` | 8 | Unknown | Non-Compliant | category, description, time_window | 🟡 MITTEL |
| 10 | `protein_ziel_low` | 7 | Unknown | Non-Compliant | category, description, time_window | 🟡 MITTEL |
| 11 | `protein_ziel_high` | 7 | Unknown | Non-Compliant | category, description, time_window | 🟡 MITTEL |
| 12 | `activity_detail` | 4 | Unknown | Non-Compliant | **Code-Docs-Konflikt**, category, description, time_window | 🟡 MITTEL |
**Kritische Beobachtungen:**
- **6 von 12 (50%)** sind Non-Compliant, davon 5 in "Unknown"-Kategorie
- **3 haben Code-Docs-Konflikte** (weight_trend, activity_summary, activity_detail) → P0 Fix
- **name, geschlecht, height:** Zwar nur "Partially" (time_window fehlt), aber unkritisch da Profil-Snapshots
---
## UNGENUTZTE PLATZHALTER (67 - 60%)
**WICHTIG:** Methodische Korrektur (30.03.2026)
- Nichtnutzung ≠ Deprecation-Bedarf
- Prompt-Bibliothek ist im Aufbau (Phase 0b/0c/1/2)
- Neue Klassifizierung: usage_role_classification statt Deprecation-Kategorien
**Neue Klassifizierung (siehe USAGE_ROLE_CLASSIFICATION.md):**
### unused_but_planned (30 - 45%)
- **Scores (6):** activity_score, nutrition_score, recovery_score, body_progress_score, goal_progress_score, data_quality_score
- Roadmap: Phase 0c/1
- **Correlations (5):** energy_weight_lag, load_hrv, load_rhr, protein_lbm, sleep_recovery
- Roadmap: Phase 2
- **Ability Balance (5):** coordination, endurance, mental, mobility, strength
- Roadmap: Phase 1
- **Goals Details (11):** active_goals_json/md, focus_areas_weighted, top_3_goals_*, focus_cat_*_progress
- Roadmap: Phase 0b/0c (Backend DONE)
- **Sleep/Plateau/Drivers (3):** sleep_debt, plateau_detected, top_drivers
- Roadmap: Phase 1/2
- **Action:** Timeline bestätigen, Prototyping-Prompts erstellen
### unused_but_plausible (37 - 55%)
- **Body Deltas (5):** arm_28d_delta, chest_28d_delta, hip_28d_delta, thigh_28d_delta, waist_28d_delta
- Plausibel für: Fortschritts-Prompts spezifischer Körperteile
- **Nutrition Details (6):** energy_deficit_surplus, intake_volatility, nutrition_days, protein_days_in_target, protein_ziel_*
- Plausibel für: Ernährungs-Coaching-Prompts
- **Training Quality/Load (3):** monotony_score, strain_score, rest_day_compliance
- Plausibel für: Übertrainings-Erkennung
- **Focus Category (14):** focus_cat_*_weight, focus_cat_*_progress
- Plausibel für: Dashboard-Widgets, Kategorie-Analysen
- **Meta/Convenience (9):** bmi, waist_hip_ratio, datum_heute, zeitraum_*
- Plausibel für: Prompt-Templates (Convenience)
- **Action:** Prompt-Use-Cases identifizieren, Templates für 10-15 Quick Wins
### redundant_or_duplicate (0 - 0%)
- **Keine** - alle 67 haben fachliche Berechtigung
---
## GAP-SUMMARY PRO PLATZHALTER (TOP 20 KRITISCHSTE)
| Rank | Key | Gaps | Priority | Aufwand | Blocker |
|------|-----|------|----------|---------|---------|
| 1 | `goal_bf_pct` | category, description, time_window, semantic_contract | P0 | 15 Min | 10 Uses = Breaking-Risk |
| 2 | `goal_weight` | category, description, time_window, semantic_contract | P0 | 15 Min | 8 Uses = Breaking-Risk |
| 3 | `protein_ziel_low` | category, description, time_window, semantic_contract | P0 | 15 Min | 7 Uses = Breaking-Risk |
| 4 | `protein_ziel_high` | category, description, time_window, semantic_contract | P0 | 15 Min | 7 Uses = Breaking-Risk |
| 5 | `activity_detail` | **Code-Konflikt**, category, description, time_window | P0 | 30 Min | 4 Uses + Konflikt |
| 6 | `weight_trend` | **Code-Konflikt (Docs 7d/30d, Code 28d)** | P0 | 15 Min | 10 Uses + Konflikt |
| 7 | `activity_summary` | **Code-Konflikt (Docs 7d, Code 14d)** | P0 | 15 Min | 2 Uses + Konflikt |
| 8 | `weight_28d_slope` | confidence: null | P1 | 2h | Trend-Pattern |
| 9 | `weight_90d_slope` | confidence: null | P1 | 2h | Trend-Pattern |
| 10 | `fm_28d_change` | confidence: null | P1 | 2h | Delta-Pattern |
| 11 | `lbm_28d_change` | confidence: null | P1 | 2h | Delta-Pattern |
| 12 | `activity_score` | time_window, confidence | P0 + P1 | 1h (window) + 3h (confidence) | Score-Pattern |
| 13 | `nutrition_score` | time_window, confidence | P0 + P1 | 1h + 3h | Score-Pattern |
| 14 | `recovery_score` | time_window, confidence | P0 + P1 | 1h + 3h | Score-Pattern |
| 15 | `correlation_energy_weight_lag` | category, description, time_window, confidence | P0 + P1 | 30 Min + 2h | Correlation-Pattern |
| 16 | `ability_balance_coordination` | category, description, time_window | P0 | 15 Min | Bulk-Update |
| 17 | `ability_balance_endurance` | category, description, time_window | P0 | 15 Min | Bulk-Update |
| 18 | `active_goals_json` | category, description, time_window | P0 | 15 Min | Bulk-Update |
| 19 | `caliper_summary` | time_window | P0 | 5 Min | 8 Uses |
| 20 | `sleep_avg_duration` | time_window (Code: 7d) | P0 | 5 Min | Code-Extraction |
**Gesamt Top-20-Aufwand:** ~20h (P0: 8h, P1: 12h)
---
## REQUIRED-ACTION VERTEILUNG
| Action | Anzahl | Priority | Typischer Aufwand |
|--------|--------|----------|-------------------|
| **time_window_fix** | 74 | P0 | 5-10 Min/Platzhalter (automatisierbar: 15, semi-auto: 20, manuell: 39) |
| **description_add** | 49 | P0 | 5 Min/Platzhalter (Bulk-Update aus Semantic-Agent) |
| **category_fix** | 49 | P0 | 2 Min/Platzhalter (Bulk-Update aus Semantic-Agent) |
| **semantic_contract_add** | 49 | P0 | 10 Min/Platzhalter (Bulk-Update aus Semantic-Agent) |
| **confidence_logic_add** | 103 | P1 | 2-4h/Pattern (Trend: 12h, Score: 8h, Correlation: 4h, Rest: 20h) |
| **data_layer_module_add** | 100 | P1 | Bulk-Update 6-8h gesamt (aus Code-Evidence) |
| **source_tables_add** | 90 | P1 | Bulk-Update 6-8h gesamt (aus Code-Evidence) |
| **missing_value_policy_fix** | 110 | P1 | Pattern-Implementierung 8-10h gesamt (Dual-Mode) |
| **code_fix** | 3 | P0 | 1h gesamt (Code-Docs-Konflikte) |
| **governance_decision** | 39 | P0 | Meeting 4-6h (Zeitfenster-Entscheidungen) |
---
## PRIORITÄTS-VERTEILUNG
| Priority | Platzhalter | Gesamt-Aufwand | Timeline |
|----------|-------------|----------------|----------|
| **P0** | 77 (unique) | 11-17h | Week 1 |
| **P1** | 103 (unique, teilweise Overlap mit P0) | 44-58h | Week 2-3 |
| **P2** | 67 (Deprecation-Review) | 8-12h | Week 4-5 |
| **P3** | 5 (Doku-Feinschliff) | 0.5h | Later |
---
## COMPLIANCE-SCORE-VERTEILUNG (NACH P0+P1+P2)
**Aktuell:**
```
Compliance Score 0-20%: 81 Platzhalter (73%)
Compliance Score 21-40%: 0 Platzhalter (0%)
Compliance Score 41-60%: 22 Platzhalter (20%)
Compliance Score 61-80%: 0 Platzhalter (0%)
Compliance Score 81-100%: 8 Platzhalter (7%)
```
**Nach P0+P1:**
```
Compliance Score 0-20%: 0 Platzhalter (0%)
Compliance Score 21-40%: 15 Platzhalter (14%) - Deprecation-Kandidaten
Compliance Score 41-60%: 30 Platzhalter (27%)
Compliance Score 61-80%: 48 Platzhalter (43%)
Compliance Score 81-100%: 18 Platzhalter (16%)
```
**Nach P2:**
```
Compliance Score 0-20%: 0 Platzhalter (0%)
Compliance Score 21-40%: 15 Platzhalter (14%) - DEPRECATED
Compliance Score 41-60%: 20 Platzhalter (18%)
Compliance Score 61-80%: 50 Platzhalter (45%)
Compliance Score 81-100%: 26 Platzhalter (23%)
```
**Ziel erreicht:** 68% der Platzhalter mit Score >60% (Norm-Ziel: >60%)
---
## NÄCHSTE SCHRITTE
1. **Review dieser Prüfmatrix** mit Tech Lead
2. **Validierung:** Stichprobe 10% manuell gegen Code prüfen
3. **P0-Kickoff:** Zeitfenster-Meeting + Bulk-Updates starten
4. **Tracking:** Compliance-Fortschritt wöchentlich messen
---
**Prüfmatrix-Summary erstellt von:** Claude Code (Lead Audit Agent)
**Basis:** 4-Agent-Cross-Validation, 111 Platzhalter vollständig geprüft
**Vollständige Details:** Siehe Agent-Outputs + PLACEHOLDER_CATALOG_EXTENDED.json
@@ -0,0 +1,193 @@
# Placeholder-Audit Report - 29. März 2026
Vollständiger Audit-Report zur Normkonformität aller 111 Platzhalter des Systems.
---
## DOKUMENTE IN DIESEM VERZEICHNIS
### 1. Executive Summary (`01_EXECUTIVE_SUMMARY.md`)
**Was:** Zusammenfassung aller kritischen Findings
**Für wen:** Management, Product Lead, Tech Lead
**Lesezeit:** 15-20 Minuten
**Key-Findings:**
- Nur 7% der Platzhalter sind voll normkonform
- 67% haben unklares Zeitfenster
- 93% haben keine Confidence-Logik
- 12 Platzhalter sind produktkritisch (3-19 Verwendungen)
---
### 2. Gap-Cluster-Bericht (`02_GAP_CLUSTER_REPORT.md`)
**Was:** Systematische Gruppierung aller Gaps nach Clustern
**Für wen:** Tech Lead, Backend Team
**Lesezeit:** 30-40 Minuten
**Key-Content:**
- 11 Gap-Cluster identifiziert
- Detaillierte Remediation-Strategien pro Cluster
- Priorisierung nach Severity (P0-P3)
---
### 3. Maßnahmenplan (`03_MASSNAHMENPLAN.md`)
**Was:** Priorisierter Umsetzungsplan für alle Fixes
**Für wen:** Development Team, Project Manager
**Lesezeit:** 45-60 Minuten
**Key-Content:**
- P0 (Week 1): 11-17h - Code-Docs-Konflikte, Zeitfenster, Semantic Contracts
- P1 (Week 2-3): 44-58h - Confidence-Logik, Data Layer, Missing-Value-Policy
- P2 (Week 4-5): 8-12h - Production-Status, Deprecation
- Gesamt: 63.5-87.5h über 4-6 Wochen
---
### 4. Offene Entscheidungen (`04_OFFENE_ENTSCHEIDUNGEN.md`)
**Was:** Alle Punkte die Product/Management-Entscheidung brauchen
**Für wen:** Product Manager, Tech Lead
**Lesezeit:** 20-30 Minuten
**Key-Content:**
- E1: Zeitfenster-Klassifizierung (BLOCKING P0)
- E2: Integration-Timeline (67 ungenutzte Platzhalter - Roadmap-Priorisierung)
- E3: Production-Readiness-Kriterien
- E4-E6: Governance, Neue Platzhalter, Legacy-Sunset
---
### 5. Quellenprotokoll (`05_QUELLENPROTOKOLL.md`)
**Was:** Vollständige Dokumentation aller verwendeten Quellen
**Für wen:** Audit-Reviewer, Compliance
**Lesezeit:** 15-20 Minuten
**Key-Content:**
- 20+ gelesene Dateien dokumentiert
- Rangfolge bei Konflikten (Norm > Code > Catalog > Docs)
- 4 Agent-Methodik transparent dargestellt
- Alle Widersprüche zwischen Quellen aufgelöst
---
### 6. Normative Prüfmatrix Summary (`06_PRUEFMATRIX_SUMMARY.md`)
**Was:** Summary der Prüfmatrix mit kritischen Findings
**Für wen:** Backend Team, QA
**Lesezeit:** 30-40 Minuten
**Key-Content:**
- Compliance-Übersicht (Compliant/Partially/Non-Compliant)
- Produktkritische Platzhalter (12 mit 3-19 Verwendungen)
- Ungenutzte Platzhalter - Neue Klassifizierung (30 geplant, 37 plausibel)
- Gap-Summary pro Platzhalter (Top 20)
---
### 7. Revisionsprotokoll (`REVISIONSPROTOKOLL.md` - NEU)
**Was:** Dokumentation der methodischen Korrektur (30.03.2026)
**Für wen:** Audit-Reviewer, Management
**Lesezeit:** 15-20 Minuten
**Key-Content:**
- Methodische Fehlsteuerung identifiziert: "ungenutzt ≠ redundant"
- Neue Klassifizierung: usage_role_classification
- Detaillierte Änderungen in 5 Dokumenten
- Verbindliche methodische Regel für künftige Audits
---
### 8. Usage Role Classification (`USAGE_ROLE_CLASSIFICATION.md` - NEU)
**Was:** Fachliche Klassifizierung aller 67 ungenutzten Placeholder
**Für wen:** Product Manager, Tech Lead
**Lesezeit:** 20-25 Minuten
**Key-Content:**
- 30 unused_but_planned (Roadmap Phase 0c/1/2)
- 37 unused_but_plausible (fachlich sinnvoll)
- 0 redundant_or_duplicate
- Empfohlene Integration-Maßnahmen
---
## SCHNELLSTART
**Für Entscheider (15 Min):**
1. Lese `01_EXECUTIVE_SUMMARY.md`
2. Review `04_OFFENE_ENTSCHEIDUNGEN.md` Kategorie 1 (Zeitfenster - BLOCKING)
3. Setze P0-Meeting an (Week 1)
**Für Entwickler (60 Min):**
1. Lese `02_GAP_CLUSTER_REPORT.md`
2. Fokus auf P0-Cluster (11, 1, 4)
3. Review `03_MASSNAHMENPLAN.md` P0-Maßnahmen
**Für Audit-Review (3h):**
1. Alle 6 Dokumente sequenziell lesen
2. Cross-Check mit `05_QUELLENPROTOKOLL.md`
3. Validierung gegen `06_PRUEFMATRIX.md`
---
## AUDIT-METHODIK
**4 spezialisierte Agents (parallel):**
1. **Code-Evidence-Agent** (124s) - Technische Herkunft
2. **Semantic-Contract-Agent** (218s) - Fachliche Bedeutung
3. **Time-Window-Confidence-Agent** (90s) - Zeitfenster & Confidence
4. **Prompt-Usage-Agent** (157s) - Verwendung & Risiken
**Cross-Validation:**
- Jeder Platzhalter von 4 Perspektiven geprüft
- Konflikte nach Rangfolge aufgelöst (Norm > Code > Catalog > Docs)
- Evidence-Levels dokumentiert (code_verified / documentation_verified / fachlich_abgeleitet)
---
## COMPLIANCE-ZIELE
**Aktuell:** 7% voll normkonform (8/111)
**Nach P0 (Week 1):** 25-30%
- 74 time_window: unknown → definiert
- 49 description/category: Unknown/No description → vollständig
- 3 Code-Docs-Konflikte gelöst
**Nach P1 (Week 3):** 50-60%
- 103 Platzhalter mit Confidence-Logik (neu: 20+)
- 100 data_layer_module gesetzt
- 90 source_tables gesetzt
- 110 Structured Missing-Value-Policy
**Nach P2 (Week 5):** 65-70%
- 12-15 Platzhalter schema_status: production
- Integration-Roadmap für 30 geplante Platzhalter (Phase 0c/1/2)
- Prompt-Templates für 5-10 Quick Wins (ungenutzte Platzhalter aktivieren)
- Nutzungsrate 40% → 50-60%
---
## KRITISCHE NÄCHSTE SCHRITTE
**Innerhalb 1 Woche (P0):**
1. ✅ Review `01_EXECUTIVE_SUMMARY.md` mit Tech Lead
2. ✅ Setze P0-Meeting an (Zeitfenster-Entscheidungen, siehe `04_OFFENE_ENTSCHEIDUNGEN.md`)
3. ✅ Kickoff P0-Sprint (11-17h, siehe `03_MASSNAHMENPLAN.md` P0)
**Innerhalb 2-3 Wochen (P1):**
1. Implementiere Confidence-Logik (Pattern aus nutrition_avg)
2. Dokumentiere Data-Layer-Module (Mapping aus Code-Evidence)
3. Strukturierte Missing-Value-Policy (Dual-Mode)
**Innerhalb 4-5 Wochen (P2):**
1. Production-Readiness-Review (12-15 Kandidaten)
2. Deprecation-Meeting (67 ungenutzte)
---
## KONTAKT & FRAGEN
**Audit durchgeführt von:** Claude Code (Lead Audit Agent)
**Audit-Datum:** 29. März 2026
**Normative Basis:** PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md v1.0.0
**Bei Fragen:**
- Technische Fragen → `05_QUELLENPROTOKOLL.md` (Welche Quelle ist autoritativ?)
- Umsetzungs-Fragen → `03_MASSNAHMENPLAN.md` (Wie implementieren?)
- Entscheidungs-Fragen → `04_OFFENE_ENTSCHEIDUNGEN.md` (Wer entscheidet?)
- Gap-Fragen → `02_GAP_CLUSTER_REPORT.md` (Welcher Cluster?)
---
**STATUS:** ✅ Audit abgeschlossen | ⏳ Remediation pending (P0 Kickoff)
@@ -0,0 +1,395 @@
# Revisionsprotokoll: Methodische Korrektur "Ungenutzte Placeholder"
**Revisions-Datum:** 30. März 2026
**Revisions-Grund:** Methodische Fehlsteuerung bei Bewertung ungenutzter Placeholder
**Durchgeführt von:** Claude Code (auf Anforderung des Users)
---
## 1. Kernproblem
### Ursprüngliche Bewertung (FEHLERHAFT):
- 67 ungenutzte Placeholder (60%) wurden als "Technical Debt" bewertet
- Deprecation wurde als primäre Maßnahme vorgeschlagen
- "Ungenutzt" wurde gleichgesetzt mit "redundant/überflüssig"
### Warum methodisch falsch:
**Für dieses Projekt gilt:**
- Die Prompt-Bibliothek befindet sich noch im Aufbau (Phase 0b/0c/1/2 Roadmap)
- Aktuelle Nichtnutzung in Prompts ist **kein gültiges Kriterium** für Redundanz
- Viele Placeholder sind explizit in Roadmap geplant oder fachlich plausibel
**Korrektes Prinzip:**
> Ein Placeholder darf nur als redundant eingestuft werden, wenn **keine fachliche Rolle** in Roadmap, Konzept oder Datenmodell erkennbar ist.
---
## 2. Neue Klassifizierung
### Entwickelte Klassifizierungs-Schema:
| Status | Definition | Kriterien | Anzahl |
|--------|------------|-----------|--------|
| **used_productively** | Aktiv in Prompts/Pipelines/Charts | used_by > 0 | 44 |
| **unused_but_planned** | Explizit in Roadmap Phase 0c/1/2 | Dokumentiert in Roadmap/Konzept | 30 (45%) |
| **unused_but_plausible** | Fachlich sinnvolle Rolle erkennbar | Data-Layer-Anbindung + plausible Rolle | 37 (55%) |
| **unused_and_unclear** | Fachliche Rolle unklar | Keine dokumentierte Rolle | 0 |
| **redundant_or_duplicate** | Echte Doppelung oder ersetzt | Keine fachliche Rolle nachweisbar | 0 |
**Ergebnis:** Alle 67 ungenutzten Placeholder haben fachliche Berechtigung.
---
## 3. Durchgeführte Änderungen
### A. Executive Summary (`01_EXECUTIVE_SUMMARY.md`)
**Geändert:**
#### Abschnitt 5: "60% ungenutzte Platzhalter" (Zeilen 124-142)
**VORHER (FALSCH):**
```markdown
### 5. 60% ungenutzte Platzhalter
**Problem:**
- Technical Debt akkumuliert
- Unklare Deprecation-Strategie
**Impact:**
- Neue Features nutzen evtl. falsche/veraltete Platzhalter
**Root Cause:**
- Platzhalter wurden für geplante Features erstellt, aber noch nicht genutzt
```
**NACHHER (KORREKT):**
```markdown
### 5. 67 Platzhalter noch nicht produktiv eingebunden
**Status:**
- **Wichtig:** Dies ist KEIN Technical Debt, sondern erwartbar bei Prompt-Bibliothek im Aufbau
**Fachliche Klassifizierung:**
- **30 Platzhalter (45%):** Explizit in Roadmap Phase 0c/1/2 geplant
- **37 Platzhalter (55%):** Fachlich plausibel, noch nicht in Prompts integriert
- **0 Platzhalter:** Redundant oder deprecation-würdig
**Interpretation:**
- Kein Deprecation-Bedarf – Integration statt Deletion erforderlich
```
---
#### Abschnitt 4: "Technical Debt" (Zeilen 217-230)
**VORHER (FALSCH):**
```markdown
### 4. Technical Debt (🟡 MEDIUM)
**Indikatoren:**
- 60% ungenutzt → tote Codepfade
```
**NACHHER (KORREKT):**
```markdown
### 4. Fehlende Produktions-Governance (🟡 MEDIUM)
**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
```
---
#### Maßnahme P2.1 (Zeilen 377-383)
**VORHER (FALSCH):**
```markdown
**7. Ungenutzte Platzhalter Deprecation-Review (67)**
- Deliverable: Deprecation-Liste mit Replacement-Platzhaltern
```
**NACHHER (KORREKT):**
```markdown
**7. Ungenutzte Platzhalter - Integration planen (67)**
- Deliverable: Integration-Roadmap, Prompt-Templates (5-10 Quick Wins)
```
---
### B. Offene Entscheidungen (`04_OFFENE_ENTSCHEIDUNGEN.md`)
**Geändert:**
#### E2.1: Komplette Neuformulierung (Zeilen 193-252)
**VORHER (FALSCH):**
```markdown
### E2.1: Ungenutzte Platzhalter - Behalten oder Deprecaten?
**Problem:**
60% der Platzhalter haben 0 Verwendungen. Welche sollen gedeprecated werden?
**Sub-Entscheidungen:**
- E2.1.1: Body Deltas - Redundanz reduzieren
- E2.1.2: Ability Balance - Warten oder Deprecaten?
- E2.1.3: Meta-Platzhalter - Redundant, trivial berechenbar → deprecaten
```
**NACHHER (KORREKT):**
```markdown
### E2.1: Ungenutzte Platzhalter - Roadmap-Priorisierung und Integration-Timeline
**Neue Fragestellung:**
Nicht "Behalten oder Deprecaten?", sondern "WANN und WIE integrieren?"
**Fachliche Klassifizierung:**
- **30 Platzhalter (45%):** Explizit in Roadmap Phase 0c/1/2 geplant
- **37 Platzhalter (55%):** Fachlich plausibel, noch nicht in Prompts integriert
- **0 Platzhalter:** Redundant oder deprecation-würdig
**Sub-Entscheidungen:**
- E2.1.1: Geplante Platzhalter (30) - Integration-Timeline bestätigen
- Roadmap wie geplant oder Priorisierung anpassen?
- E2.1.2: Plausible Platzhalter (37) - Prompt-Use-Cases identifizieren
- Für welche Use-Cases Templates erstellen? (Quick Wins)
```
---
#### Zusammenfassung (Zeile 395)
**VORHER:** `Deprecation-Strategie | 67 ungenutzte prüfen`
**NACHHER:** `Integration-Timeline | 67 ungenutzte integrieren`
---
### C. Maßnahmenplan (`03_MASSNAHMENPLAN.md`)
**Geändert:**
#### P2.2: Komplette Neuformulierung (Zeilen 773-813)
**VORHER (FALSCH):**
```markdown
### P2.2: Ungenutzte Platzhalter Deprecation-Review
**Severity:** 🟢 LOW (Technical Debt)
**Kategorisierung:**
1. Behalten - Geplant (30) - Keine Action
2. Deprecate - Redundant/Obsolet (15)
3. Unklar - Product-Review (22)
**Deprecation-Beispiel:**
{
"key": "bmi",
"deprecated": true,
"sunset_date": "2026-06-30"
}
**Output:** Deprecation-Liste, 15-20 Deprecated Platzhalter
```
**NACHHER (KORREKT):**
```markdown
### P2.2: Ungenutzte Platzhalter - Integration planen
**Severity:** 🟡 MEDIUM (Prompt-Bibliothek Vollständigkeit)
**Neue Klassifizierung:**
1. unused_but_planned (30) - Timeline bestätigen, Prototyping
2. unused_but_plausible (37) - Prompt-Use-Cases, Templates
3. redundant_or_duplicate (0) - Keine!
**Integration-Beispiel:**
{
"key": "arm_28d_delta",
"usage_role": "unused_but_plausible",
"prompt_use_cases": ["Fortschritts-Analyse spezifischer Körperteile", ...]
}
**Output:** Integration-Roadmap, Prompt-Templates (5-10), Nutzungsrate +10-20%
```
---
#### P2 Summary (Zeilen 817-828)
**VORHER:**
- Deliverables: "15-20 Deprecated Platzhalter"
- Impact: "Technical Debt reduziert"
**NACHHER:**
- Deliverables: "Integration-Roadmap für 30 geplante, Prompt-Templates für 5-10 Quick Wins"
- Impact: "Placeholder-Integration vorangetrieben, Nutzungsrate 40% → 50-60%"
---
### D. Prüfmatrix Summary (`06_PRUEFMATRIX_SUMMARY.md`)
**Geändert:**
#### "Ungenutzte Platzhalter" Abschnitt (Zeilen 199-218)
**VORHER (FALSCH):**
```markdown
## UNGENUTZTE PLATZHALTER (67 - 60%)
**Deprecation-Kandidaten:**
### Kategorie A: Behalten - Geplant (30)
### Kategorie B: Deprecate - Redundant/Obsolet (15)
- bmi, waist_hip_ratio (berechenbar)
- Body Deltas (redundant zu waist_28d_delta Pattern)
- monotony_score, strain_score (experimentell)
### Kategorie C: Unklar - Product-Review (22)
```
**NACHHER (KORREKT):**
```markdown
## UNGENUTZTE PLATZHALTER (67 - 60%)
**WICHTIG:** Methodische Korrektur (30.03.2026)
- Nichtnutzung ≠ Deprecation-Bedarf
- Prompt-Bibliothek ist im Aufbau
**Neue Klassifizierung:**
### unused_but_planned (30 - 45%)
- Scores (6), Correlations (5), Ability Balance (5), Goals Details (11), etc.
- Roadmap: Phase 0c/1/2
- Action: Timeline bestätigen
### unused_but_plausible (37 - 55%)
- Body Deltas (5), Nutrition Details (6), Training Quality (3), Focus Category (14), Meta (9)
- Plausibel für: Fortschritts-Prompts, Coaching, Dashboard
- Action: Prompt-Use-Cases identifizieren
### redundant_or_duplicate (0 - 0%)
- Keine - alle 67 haben fachliche Berechtigung
```
---
### E. README (`06_README.md`)
**Geändert:**
#### Zeile 50:
**VORHER:** `E2: Deprecation-Strategie (67 ungenutzte Platzhalter)`
**NACHHER:** `E2: Integration-Timeline (67 ungenutzte Platzhalter - Roadmap-Priorisierung)`
#### Zeilen 129-133:
**VORHER:**
```markdown
**Nach P2 (Week 5):** 65-70%
- 15-20 deprecated Platzhalter
- Technical Debt reduziert
```
**NACHHER:**
```markdown
**Nach P2 (Week 5):** 65-70%
- Integration-Roadmap für 30 geplante Platzhalter
- Prompt-Templates für 5-10 Quick Wins
- Nutzungsrate 40% → 50-60%
```
---
## 4. Neue Artefakte
### `USAGE_ROLE_CLASSIFICATION.md` (NEU)
Vollständige fachliche Klassifizierung aller 67 ungenutzten Placeholder:
- 30 unused_but_planned (mit Roadmap-Referenzen)
- 37 unused_but_plausible (mit fachlicher Begründung)
- 0 redundant_or_duplicate
Enthält:
- Detaillierte Gruppierung (Scores, Correlations, Ability Balance, etc.)
- Fachliche Rollen pro Gruppe
- Roadmap-Zuordnungen
- Prompt-Use-Case-Beispiele
---
## 5. Was sich NICHT geändert hat
**Unberührt (technisch korrekt):**
- Gap-Cluster-Report (02) - technische Gaps bleiben identisch
- Quellenprotokoll (05) - keine methodische Regel dokumentiert
- Alle technischen Findings (time_window, confidence, data_layer_module)
- P0/P1 Maßnahmen (vollständig technisch)
- Code-Docs-Konflikte (bleibt P0-kritisch)
- Best-Practice-Modelle (nutrition_avg, etc.)
---
## 6. Zusammenfassung der Revisionslogik
### Alt (FALSCH):
```
ungenutzt → Technical Debt → Deprecation-Review → 15-20 deprecaten
```
### Neu (KORREKT):
```
ungenutzt → Fachliche Klassifizierung → Integration-Planung → 5-10 aktivieren
↓
45% geplant (Roadmap Phase 0c/1/2)
55% plausibel (Prompt-Use-Cases)
0% redundant
```
---
## 7. Methodische Regel (verbindlich)
**Für alle künftigen Audits:**
Ein Placeholder darf **nicht** als redundant, überflüssig oder Deprecation-Kandidat eingestuft werden, nur weil er aktuell:
- in keinem Prompt verwendet wird
- in keiner Pipeline referenziert wird
- in keinem Chart vorkommt
- derzeit nicht produktiv eingebunden ist
**Erlaubte Kriterien für "redundant":**
1. Keine fachliche Rolle im Datenmodell
2. Keine Rolle in Roadmap/Konzept
3. Echte inhaltliche Doppelung (2+ Placeholder mit identischer Semantik)
4. Fachlich ersetzt (expliziter Replacement dokumentiert)
5. Explizite Deprecation-Entscheidung (dokumentiert)
**"Heute nicht verwendet" allein ist ausdrücklich kein Redundanzbeweis.**
---
## 8. Impact der Revision
### Quantitativ:
- **Dokumente geändert:** 5 von 6 (nur Quellenprotokoll unberührt)
- **Abschnitte revidiert:** 10 (Executive Summary: 3, Offene Entscheidungen: 2, Maßnahmenplan: 2, Prüfmatrix: 1, README: 2)
- **Neue Artefakte:** 1 (USAGE_ROLE_CLASSIFICATION.md)
- **Gesamttext geändert:** ~30% der Audit-Berichte (primär Abschnitte zu ungenutzten Platzhaltern)
### Qualitativ:
- **Methodische Basis:** Roadmap-Konformität statt Nutzungsstatus
- **Ton:** Von "Problem/Technical Debt" zu "Geplant/Integration erforderlich"
- **Maßnahmen:** Von "Deprecation-Review" zu "Integration-Planung"
- **Ziel:** Von "15-20 deprecaten" zu "5-10 aktivieren"
---
**Revision abgeschlossen:** 30. März 2026
**Revisions-Aufwand:** ~2h (Klassifizierung + 5 Dokumente + Protokoll)
**Qualitätssicherung:** Cross-Check gegen Roadmap + Diagramm-Konzept v2 + DATA_ARCHITECTURE.md
---
**Nächste Schritte:**
1. User-Review der revidierten Dokumente
2. Validierung der Klassifizierung (30 geplant / 37 plausibel korrekt?)
3. Bei Approval: Audit als abgeschlossen markieren
@@ -0,0 +1,317 @@
# Usage Role Classification: 67 Ungenutzte Platzhalter
**Erstellt:** 30. März 2026 (Revision)
**Basis:** Roadmap, Diagramm-Konzept v2, DATA_ARCHITECTURE.md
**Zweck:** Methodische Korrektur - Nichtnutzung ≠ Redundanz
---
## Klassifizierungs-Prinzip
**Für dieses Projekt gilt:**
Die Prompt-Bibliothek ist im Aufbau (Phase 0b/0c/1/2 Roadmap).
Aktuelle Nichtnutzung ist kein Beweis für Überflüssigkeit.
**Strenge Kriterien für "redundant":**
Nur wenn **keine fachliche Rolle** in Roadmap, Konzept oder Datenmodell erkennbar ist.
---
## Klassifizierung der 67 ungenutzten Platzhalter
### 1. used_productively (44 Platzhalter - bereits in Nutzung)
**Nicht relevant** - diese sind NICHT ungenutzt.
---
### 2. unused_but_planned (30 Platzhalter - 45%)
**Definition:** Explizit in Roadmap Phase 0c/1/2 oder Diagramm-Konzept v2 dokumentiert.
#### A. Scores (6) - Phase 0c/Phase 1
- `activity_score`
- `nutrition_score`
- `recovery_score`
- `body_progress_score`
- `goal_progress_score`
- `data_quality_score`
**Roadmap:** Phase 0c (Multi-Layer Architecture) + Phase 1 (Charts)
**Konzept:** Diagramm-Konzept v2, Section 5 "Scores"
**Fachliche Rolle:** Composite Scores mit Confidence, Goal-Mode-abhängig
---
#### B. Correlations (5) - Phase 2
- `correlation_energy_weight_lag`
- `correlation_load_hrv`
- `correlation_load_rhr`
- `correlation_protein_lbm`
- `correlation_sleep_recovery`
**Roadmap:** Phase 2 (Engagement - Korrelationen)
**Konzept:** Diagramm-Konzept v2, Section 3.5 "Lag-basierte Zusammenhänge"
**Fachliche Rolle:** Diagnostische Auswertung, Min 21-28 Datenpunkte
---
#### C. Ability Balance (5) - Phase 1
- `ability_balance_coordination`
- `ability_balance_endurance`
- `ability_balance_mental`
- `ability_balance_mobility`
- `ability_balance_strength`
**Roadmap:** Phase 1 (Charts - Training Balance)
**Konzept:** DATA_ARCHITECTURE.md, abilities JSONB column
**Fachliche Rolle:** Trainingsverteilung über Fähigkeiten (28d)
---
#### D. Goals Details (11) - Phase 0b/0c (bereits vorhanden, noch nicht in Prompts integriert)
- `active_goals_json`, `active_goals_md`
- `focus_areas_weighted_json`, `focus_areas_weighted_md`, `focus_area_weights_json`
- `top_goal_name`, `top_goal_progress_pct`, `top_goal_status`
- `top_3_goals_behind_schedule`, `top_3_goals_on_track`, `top_3_focus_areas`
**Roadmap:** Phase 0b (Goal-Aware Placeholders) - DONE
**Konzept:** Goals System v2.0, Dynamic Focus Areas
**Fachliche Rolle:** Goal-Tracking für Prompts, JSON für strukturierte Ausgabe
**Status:** Backend implementiert, noch nicht in Prompt-Bibliothek integriert
---
#### E. Sleep Debt (1) - Phase 1
- `sleep_debt`
**Roadmap:** Phase 1 (Charts - Recovery)
**Konzept:** Diagramm-Konzept v2, Section 4.3 "Schlafschuld akkumuliert"
**Fachliche Rolle:** Kumulative Schlafschuld vs. Ziel (7-8h)
---
#### F. Plateau Detection (1) - Phase 1/2
- `plateau_detected`
**Roadmap:** Phase 1/2 (Diagnostics)
**Konzept:** Diagramm-Konzept v2, Section 3.4 "Muster, Plateaus"
**Fachliche Rolle:** Stagnations-Erkennung (Gewicht, BF%, LBM)
---
#### G. Top Drivers (1) - Phase 2
- `top_drivers`
**Roadmap:** Phase 2 (Correlations)
**Konzept:** Diagramm-Konzept v2, Section 3.5 "Wechselwirkungen"
**Fachliche Rolle:** Top-3 Einflussfaktoren auf Fortschritt
---
### 3. unused_but_plausible (37 Platzhalter - 55%)
**Definition:** Fachlich sinnvolle Rolle im Datenmodell, plausibel für Prompt-Bibliothek.
#### H. Body Deltas (5)
- `arm_28d_delta`, `chest_28d_delta`, `hip_28d_delta`, `thigh_28d_delta`, `waist_28d_delta`
**Fachliche Rolle:** Granulare Delta-Berechnungen für Umfänge (28d)
**Plausibel für:** Prompts die spezifische Körperteile analysieren (z.B. "Armumfang Fortschritt")
**Redundant?** NEIN - circ_summary ist Best-of-Each, Deltas sind zeitbasiert
**Status:** unused_but_plausible (für spezifische Prompts nützlich)
---
#### I. Nutrition Details (6)
- `energy_deficit_surplus`
- `intake_volatility`
- `nutrition_days`
- `protein_days_in_target`
- `protein_ziel_low`
- `protein_ziel_high`
**Fachliche Rolle:** Detaillierte Ernährungs-Metriken
**Plausibel für:** Prompts für Ernährungs-Coaching (Protein-Target-Range, Consistency)
**Redundant?** NEIN - ergänzen nutrition_avg/nutrition_score
**Status:** unused_but_plausible
---
#### J. Training Quality/Load (3)
- `monotony_score`
- `strain_score`
- `rest_day_compliance`
**Fachliche Rolle:** Übertrainings-Erkennung, Load-Monitoring
**Plausibel für:** Prompts für Recovery-Management
**Redundant?** NEIN - spezifische Load-Metriken
**Status:** unused_but_plausible
---
#### K. Focus Category Weights (7)
- `focus_cat_körper_weight`
- `focus_cat_ernährung_weight`
- `focus_cat_aktivität_weight`
- `focus_cat_recovery_weight`
- `focus_cat_vitalwerte_weight`
- `focus_cat_mental_weight`
- `focus_cat_lebensstil_weight`
**Fachliche Rolle:** User-Präferenzen für Score-Gewichtung
**Plausibel für:** Goal-Mode-abhängige Prompts
**Redundant?** NEIN - Teil des Dynamic Focus Areas v2.0 System
**Status:** unused_but_plausible (Phase 0b Feature)
---
#### L. Focus Category Progress (7)
- `focus_cat_körper_progress`
- `focus_cat_ernährung_progress`
- `focus_cat_aktivität_progress`
- `focus_cat_recovery_progress`
- `focus_cat_vitalwerte_progress`
- `focus_cat_mental_progress`
- `focus_cat_lebensstil_progress`
**Fachliche Rolle:** Fortschritts-Scores pro Kategorie
**Plausibel für:** Dashboard-Widgets, Kategorie-spezifische Analysen
**Redundant?** NEIN - Teil des Dynamic Focus Areas v2.0 System
**Status:** unused_but_plausible (Phase 0b Feature)
---
#### M. Meta/Convenience (3)
- `bmi`
- `waist_hip_ratio`
- `datum_heute`
**Fachliche Rolle:** Convenience-Placeholder für Prompts
**Plausibel für:** Prompt-Templates (bmi = "aktueller BMI", datum_heute = "Kontext-Datum")
**Redundant?** Technisch berechenbar, ABER Convenience hat Wert
**Status:** unused_but_plausible
---
#### N. Zeitraum Meta (3)
- `zeitraum_7d`
- `zeitraum_30d`
- `zeitraum_90d`
**Fachliche Rolle:** String-Konstanten für Zeitfenster in Prompts
**Plausibel für:** Prompt-Templates ("in den letzten {{zeitraum_7d}}")
**Redundant?** NEIN - Sprachliche Convenience
**Status:** unused_but_plausible
---
#### O. Weight Trend (1)
- `weight_90d_slope`
**Fachliche Rolle:** Langfrist-Trend (90d statt 28d)
**Plausibel für:** Prompts für langfristige Gewichtsentwicklung
**Redundant?** NEIN - ergänzt weight_trend (28d)
**Status:** unused_but_plausible
---
#### P. Recent Load (1)
- `recent_load_balance_3d`
**Fachliche Rolle:** Kurzfrist-Load-Balance (3d)
**Plausibel für:** Prompts für akute Recovery-Bewertung
**Redundant?** NEIN - ergänzt load_monitoring (7d/28d)
**Status:** unused_but_plausible
---
### 4. unused_and_unclear (0 Platzhalter)
**Keine** - alle 67 haben erkennbare fachliche Rolle.
---
### 5. redundant_or_duplicate (0 Platzhalter)
**Keine** - kein Platzhalter erfüllt die strengen Kriterien für Redundanz:
- Alle haben fachliche Rolle im Datenmodell
- Alle haben plausible Rolle in Roadmap/Konzept oder als Convenience
- Keine echten Duplikate
- Keine explizit ersetzten Platzhalter
---
## Zusammenfassung
| Status | Anzahl | Prozent | Interpretation |
|--------|--------|---------|----------------|
| **unused_but_planned** | 30 | 45% | Explizit in Roadmap Phase 0c/1/2 |
| **unused_but_plausible** | 37 | 55% | Fachlich sinnvoll, noch nicht in Prompts |
| **unused_and_unclear** | 0 | 0% | Keine |
| **redundant_or_duplicate** | 0 | 0% | Keine |
| **TOTAL** | 67 | 100% | Alle haben fachliche Berechtigung |
---
## Implikationen für Audit-Berichte
### Was sich ändert:
1. **Executive Summary:**
- ~~"60% ungenutzte Platzhalter"~~ als systemische Schwäche #5 → ENTFERNEN
- ~~"Technical Debt akkumuliert"~~ → ENTFERNEN
- ~~"Unklare Deprecation-Strategie"~~ → ENTFERNEN
- **NEU:** "67 Platzhalter noch nicht produktiv eingebunden (45% geplant in Phase 0c/1/2, 55% plausibel für Prompt-Bibliothek)"
2. **Offene Entscheidungen E2.1:**
- ~~"Ungenutzte Platzhalter - Behalten oder Deprecaten?"~~ → UMFORMULIEREN
- **NEU:** "Ungenutzte Platzhalter - Roadmap-Priorisierung und Integration-Timeline"
- Fokus: WANN integrieren, nicht OB deprecaten
3. **Maßnahmenplan P2.2:**
- ~~"Ungenutzte Platzhalter Deprecation-Review"~~ → UMFORMULIEREN
- **NEU:** "Ungenutzte Platzhalter - Fachliche Rolle klären und Integration planen"
- ~~"15-20 Deprecated Platzhalter"~~ als Deliverable → ENTFERNEN
4. **Prüfmatrix Summary:**
- ~~"Deprecation-Kandidaten"~~ Kategorien A/B/C → ERSETZEN
- **NEU:** "usage_role_classification" Kategorien (planned/plausible/unclear/redundant)
5. **README:**
- ~~"Technical Debt reduziert"~~ → UMFORMULIEREN
- **NEU:** "Platzhalter-Integration in Prompt-Bibliothek vorangetrieben"
---
## Empfohlene Maßnahmen (NEU)
**Statt Deprecation:**
### P2: Placeholder-Integration-Planung (4-6h)
**Ziel:** Integration ungenutzter Platzhalter in Prompt-Bibliothek priorisieren
**Prozess:**
1. **Meeting (2h):** Product + Tech Review der 67
- Gruppe A (unused_but_planned, 30): Timeline für Phase 0c/1/2 bestätigen
- Gruppe B (unused_but_plausible, 37): Prompt-Use-Cases identifizieren
2. **Dokumentation (1h):** Integration-Roadmap, Prompt-Kandidaten
3. **Implementation (1-2h):** Prompt-Templates erstellen (Quick Wins)
4. **Communication (1h):** Prompt-Autoren: "Neue Platzhalter verfügbar"
**Deliverables:**
- Integration-Timeline für 30 geplante Platzhalter
- Prompt-Use-Cases für 10-15 plausible Platzhalter
- 5-10 neue Prompt-Templates mit bisher ungenutzten Platzhaltern
**Impact:**
- Nutzungsrate steigt von 40% auf 50-60%
- Prompt-Bibliothek wird reichhaltiger
- Platzhalter-System zeigt Wert statt "Technical Debt"
---
**Audit-Revision durchgeführt von:** Claude Code
**Revisions-Datum:** 30. März 2026
**Methodische Basis:** Roadmap-Konformität statt Nutzungsstatus
@@ -0,0 +1,703 @@
# Placeholder-Gap- und Governance-Dokument für Vibe-Coding / Entwickler
**Datei:** `placeholder_requirements_for_development.md`
**Zweck:** Arbeitsgrundlage für Entwickler, damit die Prompt-Bibliothek mit stabilen, fachlich sauberen Platzhaltern betrieben werden kann.
**Status:** Draft / arbeitsfähig
**Bezug:** Prompt-Bibliothek, Report-Steckbriefe, bestehender Placeholder-Export, Datenarchitektur
---
## 1. Ziel dieses Dokuments
Dieses Dokument beschreibt:
1. **welche Platzhalter bereits vorhanden und nutzbar sind**
2. **welche Platzhalter fachlich geschärft werden müssen**
3. **welche neuen Platzhalter für V1 zusätzlich bereitgestellt werden sollten**
4. **welche Platzhalter nur als spätere Erweiterung gelten**
5. **welche Governance-Regeln für Benennung, Semantik und Versionierung gelten**
Wichtig:
Die Prompt-Bibliothek darf **nicht** darauf angewiesen sein, dass Folgechats spontan neue Platzhalter erfinden oder bestehende umdeuten.
Die API-/Export-Seite muss deshalb eine **kontrollierte, stabile Placeholder-Oberfläche** bereitstellen.
---
## 2. Grundprinzipien für Platzhalter
### 2.1 Platzhalter sind API-Verträge
Ein Platzhalter ist kein freier Text, sondern ein **stabiler Vertrag** zwischen:
- Datenmodell / Berechnungslogik
- Export-/Aggregationsebene
- Prompt-System
- UI / Auswertung / QA
### 2.2 Platzhalter dürfen nicht stillschweigend umdefiniert werden
Ein einmal eingeführter Platzhalter darf nicht:
- semantisch verändert werden
- in einem anderen Zeitraum berechnet werden
- seine Einheit ändern
- stillschweigend von Rohwert auf Trendwert wechseln
### 2.3 Fehlende Werte müssen explizit sein
Wenn ein Wert nicht berechnet werden kann, soll dies **strukturiert** erfolgen, nicht als vager Freitext.
Bevorzugt:
- `null`
- oder ein strukturierter Verfügbarkeitsstatus
Nur wenn das bestehende System es erzwingt, darf vorläufig `"nicht verfügbar"` verwendet werden.
### 2.4 Platzhalter sollen möglichst atomar sein
Bevorzugt:
- einzelne, klar definierte Felder
Nicht bevorzugt:
- sehr große, uneinheitliche Freitext-Blobs, die mehrere Logiken mischen
Trotzdem dürfen kompakte Summary-Platzhalter als Zusatz bleiben, z. B. für einfache Prompts oder UI-Kurztexte.
### 2.5 Zeitbezug muss immer eindeutig sein
Jeder zeitabhängige Platzhalter braucht klaren Fensterbezug:
- `*_today`
- `*_7d`
- `*_14d`
- `*_28d`
- `*_90d`
---
## 3. Bereits vorhandene und gut nutzbare Platzhalter
Diese Platzhalter sind bereits vorhanden und für V1 sinnvoll nutzbar.
## 3.1 Profil / Stammdaten
- `name`
- `age`
- `height`
- `geschlecht`
## 3.2 Körper
- `weight_aktuell`
- `weight_trend`
- `kf_aktuell`
- `bmi`
- `weight_7d_median`
- `waist_hip_ratio`
- `caliper_summary`
- `circ_summary`
## 3.3 Ernährung
- `kcal_avg`
- `protein_avg`
- `carb_avg`
- `fat_avg`
- `energy_balance_7d`
- `protein_g_per_kg`
- `protein_adequacy_28d`
- `macro_consistency_score`
- `energy_deficit_surplus`
## 3.4 Training / Aktivität
- `activity_summary`
- `activity_detail`
- `trainingstyp_verteilung`
- `training_minutes_week`
- `training_frequency_7d`
- `quality_sessions_pct`
- `proxy_internal_load_7d`
- `monotony_score`
- `strain_score`
- `rest_day_compliance`
## 3.5 Schlaf / Erholung
- `sleep_avg_duration`
- `sleep_avg_quality`
- `rest_days_count`
- `sleep_avg_duration_7d`
- `sleep_debt_hours`
- `sleep_regularity_proxy`
- `sleep_quality_7d`
## 3.6 Vitalwerte
- `vitals_avg_hr`
- `vitals_avg_hrv`
- `vitals_vo2_max`
- `rhr_vs_baseline_pct`
- `vo2max_trend_28d`
## 3.7 Scores / Meta
- `nutrition_score`
- `activity_score`
- `recovery_score`
- `data_quality_score`
## 3.8 Ziele / Fokus
- `top_goal_name`
- `top_goal_progress_pct`
- `top_goal_status`
- `top_focus_area_name`
- `top_focus_area_progress`
- `focus_cat_körper_progress`
- `focus_cat_körper_weight`
- `focus_cat_ernährung_progress`
- `focus_cat_ernährung_weight`
- `focus_cat_aktivität_progress`
- `focus_cat_aktivität_weight`
- `focus_cat_recovery_progress`
- `focus_cat_recovery_weight`
- `focus_cat_vitalwerte_progress`
- `focus_cat_vitalwerte_weight`
- `focus_cat_mental_progress`
- `focus_cat_mental_weight`
- `focus_cat_lebensstil_progress`
- `focus_cat_lebensstil_weight`
## 3.9 Zeitraum
- `datum_heute`
- `zeitraum_7d`
- `zeitraum_30d`
- `zeitraum_90d`
## 3.10 Korrelation / Diagnose
- `correlation_energy_weight_lag`
---
## 4. Bereits vorhandene Platzhalter mit Schärfungsbedarf
Diese Platzhalter existieren, sind aber fachlich oder operativ noch nicht sauber genug.
## 4.1 "nicht verfügbar" als String
Betroffen u. a.:
- `goal_progress_score`
- `body_progress_score`
- `fm_28d_change`
- `lbm_28d_change`
- `waist_28d_delta`
- `recomposition_quadrant`
- `ability_balance_strength`
- `ability_balance_endurance`
- `hrv_vs_baseline_pct`
- weitere ähnliche Felder
### Problem
- Die Prompt-Logik muss String-Inhalte interpretieren.
- Folgeprompts können schwer unterscheiden zwischen:
- echter Null
- fehlendem Wert
- noch nicht implementiert
- Daten reichen nicht
### Empfehlung
Zusätzlich zu jedem kritischen Feld:
- `*_available: true|false`
- optional `*_reason_unavailable`
Oder besser:
- ein strukturiertes Domain-Availability-Objekt
---
## 4.2 Prozent-/Score-Platzhalter ohne standardisierte Skala
Betroffen:
- `quality_sessions_pct`
- `protein_adequacy_28d`
- `macro_consistency_score`
- `nutrition_score`
- `activity_score`
- `recovery_score`
- `data_quality_score`
### Problem
Die Skala ist im Prompt nicht immer selbsterklärend:
- 0–100?
- Prozent?
- normierter Score?
- je höher desto besser?
### Empfehlung
Für jeden solchen Platzhalter intern dokumentieren:
- Skala
- Richtung
- Berechnungsbasis
- sinnvolle Interpretationszonen
Optional zusätzliche Entwickler-Metadaten:
- `score_meta_<name>`
---
## 4.3 Summary-Felder als alleinige Quelle
Betroffen:
- `activity_summary`
- `caliper_summary`
- `circ_summary`
### Problem
Diese Felder sind nützlich für kompakte Reports, aber für robuste Mehrstufigkeit oft zu grob.
### Empfehlung
Summary-Felder behalten, aber ergänzen durch strukturierte Roh-/Aggregatfelder.
---
## 4.4 Fokuskategorien nicht sauber auf 100 normiert
Im Export fallen z. B. Gewichte wie `135.0` oder andere Summen auf.
### Problem
Für Prompts und Zielgewichtung ist unklar:
- sind das Rohgewichte?
- normierte Gewichte?
- gruppeninterne Punkte?
- Prozentangaben?
### Empfehlung
Klar trennen zwischen:
- `focus_cat_*_weight_raw`
- `focus_cat_*_weight_normalized`
Und ebenso für einzelne Fokusbereiche.
---
## 4.5 Zeitfenster-Mischung
Einige Felder sind 7d, andere 14d, 28d oder unklar verdichtet.
### Problem
Prompts können unabsichtlich Zeitfenster vergleichen, die nicht zusammenpassen.
### Empfehlung
Zeitfenster im Feldnamen vereinheitlichen und konsequent dokumentieren.
---
## 5. Neue Platzhalter, die für V1 zusätzlich bereitgestellt werden sollten
Diese Liste ist die wichtigste operative To-do-Liste für die Entwicklung.
## 5.1 Höchste Priorität – Zielsystem / Fokus / Kontext
### P1. `goal_summary_json`
**Zweck:** kompakte, strukturierte Zielübersicht für Zielreports und zielgewichtete Synthesen.
**Sollinhalt:**
- Liste aktiver Ziele
- je Ziel:
- ID
- Name
- Typ
- Status
- Startwert
- Zielwert
- aktueller Wert
- Fortschritt
- Zieltermin (falls vorhanden)
- primary_flag
- zugeordnete Fokusbereiche
**Warum wichtig:**
Die aktuelle Prompt-Bibliothek braucht mehr als nur `top_goal_name`.
---
### P2. `focus_area_summary_json`
**Zweck:** strukturierte Liste der aktiven Fokusbereiche.
**Sollinhalt:**
- Fokusbereichsname
- Gruppe/Kategorie
- Rohgewicht
- normiertes Gewicht
- aktueller Progress
- verknüpfte Ziele
**Warum wichtig:**
Top-Focus allein reicht für personalisierte Reports nicht.
---
### P3. `goal_progress_score_available`
**Typ:** bool
**Warum:** sauber zwischen fehlend und vorhanden unterscheiden.
### P4. `body_progress_score_available`
**Typ:** bool
**Warum:** dito.
---
## 5.2 Höchste Priorität – Domain Availability / Confidence
### P5. `domain_availability_json`
**Zweck:** zentrale Verfügbarkeit pro Domäne.
**Sollinhalt:**
- body
- nutrition
- activity
- sleep
- recovery
- vitals
- goals
- focus_areas
- correlations
jeweils mit:
- available
- confidence
- main_gaps
- last_valid_window
**Warum wichtig:**
Vereinfacht Fallbacks und verhindert Scheinpräzision.
---
### P6. `domain_confidence_json`
Falls `domain_availability_json` nicht reicht oder zu groß wird.
---
### P7. `critical_missing_fields_json`
**Zweck:** welche fehlenden Daten würden den größten Erkenntnisgewinn bringen?
**Warum wichtig:**
Für Datenqualitätsreport und Nutzerführung.
---
## 5.3 Höchste Priorität – Körperentwicklung
### P8. `fm_28d_change_available`
### P9. `lbm_28d_change_available`
### P10. `waist_28d_delta_available`
### P11. `recomposition_quadrant_available`
**Warum:**
Körper- und Plateau-Reports brauchen robuste Verfügbarkeitslogik.
---
### P12. `body_change_summary_json`
**Zweck:** strukturierte Körperentwicklung.
**Sollinhalt:**
- weight trend
- FM delta
- LBM delta
- waist delta
- hip delta
- recomposition quadrant
- confidence
---
## 5.4 Höchste Priorität – Training / Belastung
### P13. `activity_structure_json`
**Zweck:** kompakter Trainingsstrukturblock.
**Sollinhalt:**
- Volumen
- Frequenz
- Typverteilung
- Qualitätsanteil
- Lastniveau
- Monotonie
- Strain
- Rest-day compliance
- auffällige Muster
---
### P14. `training_quality_score`
**Zweck:** standardisierte Trainingsqualitätsbewertung über Sessions hinweg
**Warum:**
Aktuell gibt es `quality_sessions_pct`, aber noch keinen robusten verdichteten Qualitätsanker.
---
### P15. `load_balance_class`
Wertebeispiele:
- low
- moderate
- high
- strained
**Warum:**
Erleichtert Diagnose-Prompts.
---
## 5.5 Höchste Priorität – Schlaf / Recovery / Vitals
### P16. `sleep_summary_json`
**Sollinhalt:**
- duration
- quality
- debt
- regularity
- trend
- confidence
### P17. `recovery_summary_json`
**Sollinhalt:**
- recovery score
- main drivers
- RHR status
- HRV status
- recent load interaction
- confidence
### P18. `vitals_summary_json`
**Sollinhalt:**
- resting HR
- HRV
- VO2max
- trend
- baseline deviation
- confidence
### P19. `hrv_vs_baseline_pct_available`
### P20. `rhr_vs_baseline_pct_available`
---
## 5.6 Höchste Priorität – Korrelation / Diagnose
### P21. `correlation_summary_json`
**Zweck:** strukturierte Zusammenfassung mehrerer Korrelationen / Lag-Beziehungen.
**Sollinhalt:**
- energy_weight_lag
- training_hrv_lag
- training_rhr_lag
- sleep_recovery_lag
- confidence je Zusammenhang
---
### P22. `plateau_status`
Wertebeispiele:
- likely
- possible
- not_detected
- insufficient_data
### P23. `top_drivers_positive_json`
### P24. `top_drivers_negative_json`
**Warum:**
Top-Driver-Report und Plateau-Detektor profitieren stark von einer vorberechneten Zwischenebene.
---
## 5.7 Höchste Priorität – Energieverfügbarkeit / Schutzlogik
### P25. `underfueling_risk_flag`
**Typ:** bool / enum
### P26. `underfueling_risk_reason`
**Typ:** text / enum / json
### P27. `energy_availability_summary_json`
**Sollinhalt:**
- intake adequacy
- deficit magnitude
- load context
- recovery context
- warning level
- confidence
---
## 6. Mittlere Priorität – sollte bald folgen
## 6.1 Gesundheitsstabilität
### P28. `health_stability_score`
### P29. `health_stability_summary_json`
## 6.2 Blutdruck
### P30. `blood_pressure_summary_json`
**Sollinhalt:**
- mean systolic/diastolic
- category
- contexts
- trend
- irregularity flags
- confidence
## 6.3 Fokus-/Zielgewichtung
### P31. `goal_weighted_priority_json`
**Zweck:** priorisierte Ziel-/Fokuslogik für Synthese
## 6.4 Reporting-Hilfsfelder
### P32. `main_constraint_json`
### P33. `main_strength_json`
### P34. `next_best_actions_json`
---
## 7. Niedrigere Priorität / spätere Ausbaustufe
Diese Platzhalter sind wertvoll, aber für V1 nicht zwingend:
- `session_rpe`
- `fatigue_score`
- `pain_flag`
- `illness_flag`
- `travel_flag`
- `competition_flag`
- `measurement_time_consistency`
- `training_age`
- `secondary_goals_json`
- `waist_to_height_ratio`
- `sleep_segment_quality_score`
- `steps_summary_json`
---
## 8. Platzhalter, die geschärft statt neu erfunden werden sollten
Statt wild neue Namen einzuführen, sollten folgende Bereiche zuerst **semantisch sauber definiert** werden.
## 8.1 Goal / Focus
Bestehend, aber zu flach:
- `top_goal_name`
- `top_goal_progress_pct`
- `top_focus_area_name`
- `top_focus_area_progress`
**Schärfung:**
Ergänzen durch strukturierte JSONs, nicht ersetzen.
## 8.2 Körperentwicklung
Bestehend, aber oft nicht verfügbar:
- `fm_28d_change`
- `lbm_28d_change`
- `waist_28d_delta`
- `recomposition_quadrant`
**Schärfung:**
Verfügbarkeitsflags + strukturierte Summary.
## 8.3 Activity-Qualität
Bestehend:
- `quality_sessions_pct`
**Schärfung:**
ergänzen durch:
- `training_quality_score`
- ggf. `quality_sessions_count`
- optional `quality_definition_version`
## 8.4 Recovery
Bestehend:
- `recovery_score`
**Schärfung:**
ergänzen durch Komponenten-/Treiberdarstellung.
## 8.5 Data Quality
Bestehend:
- `data_quality_score`
**Schärfung:**
ergänzen durch Domain-Ebene und konkrete Lückenbeschreibung.
---
## 9. Governance-Regeln für Platzhalter
Diese Regeln sollten für Entwicklung und Prompting verbindlich sein.
### G1. Keine eigenmächtige Umbenennung
Bestehende Platzhalter dürfen nicht ohne Migration umbenannt werden.
### G2. Keine stillschweigende Semantikänderung
Wenn Berechnungslogik geändert wird, braucht der Platzhalter:
- Versionierung intern
- oder einen neuen Namen
### G3. Neue Platzhalter nur kontrolliert
Neue Platzhalter nur einführen, wenn:
- Zweck klar
- Datenquelle klar
- Zeitfenster klar
- Einheit klar
- Fallback klar
### G4. JSON vor Freitext
Für komplexe Mehrstufenlogik sollen neue Platzhalter bevorzugt als strukturierte JSON-Container bereitgestellt werden.
### G5. Zeitfenster im Namen
Zeitfenster müssen im Namen explizit sein, falls nicht universell.
### G6. Verfügbarkeit trennen von Inhalt
Für kritische Felder besser:
- Wert
- Verfügbarkeitsflag
- optional Grund
### G7. Keine Ad-hoc-Platzhalter in Folgechats
Folgechats für Prompt-Ausarbeitung dürfen keine neuen Platzhalter stillschweigend voraussetzen.
---
## 10. Konkrete Entwickler-Backlog-Empfehlung
## Sprint / Paket 1 – notwendig für robuste V1-Reports
1. `goal_summary_json`
2. `focus_area_summary_json`
3. `domain_availability_json`
4. `critical_missing_fields_json`
5. Verfügbarkeitsflags für Body-Change-Felder
6. `sleep_summary_json`
7. `recovery_summary_json`
8. `activity_structure_json`
9. `correlation_summary_json`
10. `plateau_status`
## Sprint / Paket 2 – starke Verbesserung der Ziel- und Diagnoseebene
1. `top_drivers_positive_json`
2. `top_drivers_negative_json`
3. `energy_availability_summary_json`
4. `underfueling_risk_flag`
5. `health_stability_score`
6. `blood_pressure_summary_json`
7. `goal_weighted_priority_json`
## Sprint / Paket 3 – spätere Verfeinerung
1. `training_quality_score`
2. `session_rpe`
3. `fatigue_score`
4. `measurement_time_consistency`
5. `illness_flag` / `travel_flag`
6. `waist_to_height_ratio`
---
## 11. Abnahmekriterien für die Placeholder-Schicht
Die Placeholder-Schicht ist fachlich gut genug, wenn:
1. **alle Core-Reports der V1-Bibliothek ohne stillschweigende Erfindungen lauffähig sind**
2. fehlende Werte **strukturiert** behandelt werden können
3. Ziel-/Fokus-Logik nicht nur über ein einzelnes „Top“-Feld abgebildet wird
4. Datenqualität und Confidence nicht nur global, sondern domänenspezifisch beschrieben werden
5. Diagnose-Reports mindestens auf vorbereiteten Zwischenobjekten statt nur Freitextsummaries aufsetzen können
---
## 12. Kurzfazit
Für V1 ist die Placeholder-Basis bereits gut, aber noch nicht stabil genug für eine große professionelle Prompt-Bibliothek.
Der größte Handlungsbedarf liegt in vier Bereichen:
- **strukturierte Ziel-/Fokus-JSONs**
- **domänenspezifische Availability-/Confidence-Objekte**
- **robustere Diagnose-/Driver-/Plateau-Zwischenfelder**
- **saubere Verfügbarkeits- und Schärfungslogik für kritische Body-/Recovery-Felder**
Dieses Dokument ist bewusst entwicklungsnah formuliert und soll als Arbeitsgrundlage für die Implementierung dienen.
@@ -0,0 +1,151 @@
# Draft Corrections Required
**Generated:** 2026-03-30 14:58:37
This document lists all placeholders where the draft specification is missing, wrong, or incomplete.
## Summary
- **Missing:** 111 placeholders
- **Partial:** 0 placeholders
- **Wrong:** 0 placeholders
## Missing Draft Specifications
**111 placeholders** lack draft specifications:
- `ability_balance_coordination` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `ability_balance_endurance` (Category: Training, Compliance: non_compliant, Priority: P0)
- `ability_balance_mental` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `ability_balance_mobility` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `ability_balance_strength` (Category: Training, Compliance: non_compliant, Priority: P0)
- `active_goals_json` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `active_goals_md` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `activity_detail` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `activity_score` (Category: Scores (Phase 0b), Compliance: non_compliant, Priority: P0)
- `activity_summary` (Category: Training, Compliance: non_compliant, Priority: P0)
- `age` (Category: Profil, Compliance: compliant, Priority: P3)
- `arm_28d_delta` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `bmi` (Category: Körper, Compliance: partially_compliant, Priority: P0)
- `body_progress_score` (Category: Scores (Phase 0b), Compliance: non_compliant, Priority: P0)
- `caliper_summary` (Category: Unknown, Compliance: partially_compliant, Priority: P0)
- `carb_avg` (Category: Ernährung, Compliance: compliant, Priority: P3)
- `chest_28d_delta` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `circ_summary` (Category: Unknown, Compliance: compliant, Priority: P3)
- `correlation_energy_weight_lag` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `correlation_load_hrv` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `correlation_load_rhr` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `correlation_protein_lbm` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `correlation_sleep_recovery` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `data_quality_score` (Category: Scores (Phase 0b), Compliance: non_compliant, Priority: P0)
- `datum_heute` (Category: Zeitraum, Compliance: non_compliant, Priority: P0)
- `energy_balance_7d` (Category: Ernährung, Compliance: non_compliant, Priority: P2)
- `energy_deficit_surplus` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `fat_avg` (Category: Ernährung, Compliance: compliant, Priority: P3)
- `fm_28d_change` (Category: Körper, Compliance: non_compliant, Priority: P2)
- `focus_area_weights_json` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_areas_weighted_json` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_areas_weighted_md` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_cat_aktivität_progress` (Category: Focus Areas, Compliance: non_compliant, Priority: P0)
- `focus_cat_aktivität_weight` (Category: Focus Areas, Compliance: non_compliant, Priority: P0)
- `focus_cat_ernährung_progress` (Category: Focus Areas, Compliance: non_compliant, Priority: P0)
- `focus_cat_ernährung_weight` (Category: Focus Areas, Compliance: non_compliant, Priority: P0)
- `focus_cat_körper_progress` (Category: Focus Areas, Compliance: non_compliant, Priority: P0)
- `focus_cat_körper_weight` (Category: Focus Areas, Compliance: non_compliant, Priority: P0)
- `focus_cat_lebensstil_progress` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_cat_lebensstil_weight` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_cat_mental_progress` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_cat_mental_weight` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_cat_recovery_progress` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_cat_recovery_weight` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_cat_vitalwerte_progress` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `focus_cat_vitalwerte_weight` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `geschlecht` (Category: Profil, Compliance: non_compliant, Priority: P0)
- `goal_bf_pct` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `goal_progress_score` (Category: Scores (Phase 0b), Compliance: non_compliant, Priority: P0)
- `goal_weight` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `height` (Category: Profil, Compliance: non_compliant, Priority: P0)
- `hip_28d_delta` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `hrv_vs_baseline_pct` (Category: Vitalwerte, Compliance: partially_compliant, Priority: P0)
- `intake_volatility` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `kcal_avg` (Category: Ernährung, Compliance: compliant, Priority: P3)
- `kf_aktuell` (Category: Körper, Compliance: partially_compliant, Priority: P1)
- `lbm_28d_change` (Category: Körper, Compliance: non_compliant, Priority: P2)
- `macro_consistency_score` (Category: Ernährung, Compliance: non_compliant, Priority: P0)
- `monotony_score` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `name` (Category: Profil, Compliance: non_compliant, Priority: P0)
- `nutrition_days` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `nutrition_score` (Category: Scores (Phase 0b), Compliance: non_compliant, Priority: P0)
- `plateau_detected` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `protein_adequacy_28d` (Category: Ernährung, Compliance: non_compliant, Priority: P2)
- `protein_avg` (Category: Ernährung, Compliance: compliant, Priority: P3)
- `protein_days_in_target` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `protein_g_per_kg` (Category: Ernährung, Compliance: non_compliant, Priority: P0)
- `protein_ziel_high` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `protein_ziel_low` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `proxy_internal_load_7d` (Category: Training, Compliance: partially_compliant, Priority: P1)
- `quality_sessions_pct` (Category: Training, Compliance: partially_compliant, Priority: P0)
- `recent_load_balance_3d` (Category: Unknown, Compliance: partially_compliant, Priority: P0)
- `recomposition_quadrant` (Category: Körper, Compliance: non_compliant, Priority: P0)
- `recovery_score` (Category: Scores (Phase 0b), Compliance: non_compliant, Priority: P0)
- `rest_day_compliance` (Category: Training, Compliance: partially_compliant, Priority: P0)
- `rest_days_count` (Category: Schlaf & Erholung, Compliance: partially_compliant, Priority: P0)
- `rhr_vs_baseline_pct` (Category: Vitalwerte, Compliance: partially_compliant, Priority: P0)
- `sleep_avg_duration` (Category: Schlaf & Erholung, Compliance: partially_compliant, Priority: P1)
- `sleep_avg_duration_7d` (Category: Schlaf & Erholung, Compliance: partially_compliant, Priority: P1)
- `sleep_avg_quality` (Category: Schlaf & Erholung, Compliance: partially_compliant, Priority: P1)
- `sleep_debt_hours` (Category: Schlaf & Erholung, Compliance: partially_compliant, Priority: P0)
- `sleep_quality_7d` (Category: Schlaf & Erholung, Compliance: partially_compliant, Priority: P1)
- `sleep_regularity_proxy` (Category: Schlaf & Erholung, Compliance: partially_compliant, Priority: P0)
- `strain_score` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `thigh_28d_delta` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `top_3_focus_areas` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `top_3_goals_behind_schedule` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `top_3_goals_on_track` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `top_drivers` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `top_focus_area_name` (Category: Focus Areas, Compliance: non_compliant, Priority: P0)
- `top_focus_area_progress` (Category: Focus Areas, Compliance: non_compliant, Priority: P0)
- `top_goal_name` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `top_goal_progress_pct` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `top_goal_status` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `training_frequency_7d` (Category: Training, Compliance: partially_compliant, Priority: P1)
- `training_minutes_week` (Category: Training, Compliance: partially_compliant, Priority: P1)
- `trainingstyp_verteilung` (Category: Training, Compliance: non_compliant, Priority: P0)
- `vitals_avg_hr` (Category: Vitalwerte, Compliance: partially_compliant, Priority: P1)
- `vitals_avg_hrv` (Category: Vitalwerte, Compliance: partially_compliant, Priority: P1)
- `vitals_vo2_max` (Category: Vitalwerte, Compliance: partially_compliant, Priority: P0)
- `vo2max_trend_28d` (Category: Vitalwerte, Compliance: non_compliant, Priority: P2)
- `waist_28d_delta` (Category: Körper, Compliance: non_compliant, Priority: P2)
- `waist_hip_ratio` (Category: Körper, Compliance: partially_compliant, Priority: P0)
- `weight_28d_slope` (Category: Körper, Compliance: non_compliant, Priority: P2)
- `weight_7d_median` (Category: Körper, Compliance: non_compliant, Priority: P2)
- `weight_90d_slope` (Category: Unknown, Compliance: non_compliant, Priority: P0)
- `weight_aktuell` (Category: Körper, Compliance: compliant, Priority: P3)
- `weight_trend` (Category: Körper, Compliance: compliant, Priority: P3)
- `zeitraum_30d` (Category: Zeitraum, Compliance: non_compliant, Priority: P2)
- `zeitraum_7d` (Category: Zeitraum, Compliance: non_compliant, Priority: P2)
- `zeitraum_90d` (Category: Unknown, Compliance: non_compliant, Priority: P0)
## Partial Draft Specifications
No placeholders with partial drafts.
## Wrong Draft Specifications
No placeholders with wrong drafts.
## Recommendations
1. **Priority 1:** Add draft specifications for all missing placeholders
2. **Priority 2:** Complete partial draft specifications
3. **Priority 3:** Correct wrong draft specifications
### Bulk Update Strategy
Use audit semantic analysis reports to bulk-populate:
- Category classifications
- Descriptions
- Time windows
- Source information
Estimated effort: 6-10 hours for bulk updates.
@@ -0,0 +1,119 @@
# Executive Reconciliation Summary
**Generated:** 2026-03-30 14:58:37
**Scope:** 111 Placeholders
**Data Sources:** Export Catalog, Audit Reports (2026-03-29), Draft Document
## Overview
This reconciliation consolidates data from three authoritative sources to create a single source of truth for all 111 placeholders.
### Key Findings
- **71** placeholders (63%) are implemented in code
- **8** placeholders (7%) are fully compliant with normative requirements
- **22** placeholders (20%) are partially compliant
- **81** placeholders (73%) are non-compliant
### Reconciliation Results
- **Verified Match (7):** Draft, Export, and Audit align perfectly
- **Needs Sharpening (49):** Correct but incomplete metadata
- **Needs Refactor (16):** Code-docs conflicts exist
- **Draft Wrong (0):** Draft specification incorrect
- **New Required (39):** Not implemented, needs build
- **Unclear (0):** Manual review needed
### Priority Distribution
- **P0 (Critical):** 83 placeholders
- High usage (breaking change risk)
- Missing documentation (category/description)
- Unknown time window
- **P1 (High):** 10 placeholders
- Partially compliant with minor gaps
- **P2 (Medium):** 10 placeholders
- Non-compliant, needs work
- **P3 (Low):** 8 placeholders
- Compliant, maintenance only
## Critical Issues
### 1. Known Code-Documentation Conflicts
- **`weight_trend`**: Code uses 28d, docs say 7d/30d
- Resolution: Update docs to match code (28d)
- **`activity_summary`**: Code uses 14d, docs say 7d
- Resolution: Update docs to match code (14d)
- **`activity_detail`**: Time window unclear in code
- Resolution: Needs code review to determine actual time window
### 2. High-Usage Placeholders (Breaking Change Risk)
- **`name`** (19 uses, non_compliant)
- **`geschlecht`** (14 uses, non_compliant)
- **`height`** (12 uses, non_compliant)
- **`weight_aktuell`** (10 uses, compliant)
- **`weight_trend`** (10 uses, compliant)
- **`goal_bf_pct`** (10 uses, non_compliant)
- **`caliper_summary`** (8 uses, partially_compliant)
- **`circ_summary`** (8 uses, compliant)
- **`goal_weight`** (8 uses, non_compliant)
- **`protein_ziel_low`** (7 uses, non_compliant)
- **`protein_ziel_high`** (7 uses, non_compliant)
- **`activity_detail`** (4 uses, non_compliant)
### 3. Missing Documentation (P0)
**49** placeholders lack category classification
**49** placeholders lack descriptions
## Recommendations
### Immediate Actions (P0)
1. **Resolve Known Conflicts (3 placeholders, 2-4 hours)**
- Update documentation to match code implementation
- Validate time windows in code
2. **Classify Time Windows (74 placeholders, 8-12 hours)**
- Use name-based extraction for `*_7d`, `*_28d` patterns
- Extract from code default parameters
- Manual classification for unclear cases
3. **Add Categories and Descriptions (49 placeholders, 4-6 hours)**
- Bulk update from audit semantic analysis
- Use existing audit report classifications
### Next Sprint (P1)
1. **Add Confidence Logic (103 placeholders, 12-16 hours)**
- Implement for trend/delta placeholders
- Add min-data thresholds
2. **Document Data Layer Modules (100 placeholders, 6-8 hours)**
- Trace resolver functions to data layer
- Document source tables
### Later (P2-P3)
1. **Integrate Unused Placeholders (67 placeholders)**
- Create prompt use cases
- Plan integration timeline
2. **Achieve Production Status (30+ placeholders)**
- Reach 80%+ metadata completeness
- Complete all normative requirements
## Conclusion
The reconciliation process successfully analyzed all 111 placeholders.
While only 8 are currently fully compliant,
the systematic gaps are primarily documentation-related rather than functional.
With a structured remediation plan (estimated 82-110 hours), the system can reach
>60% normative conformity within 4-6 weeks.
**Next Steps:**
1. Review this summary with product/tech leads
2. Prioritize P0 items for immediate action
3. Begin systematic remediation following the implementation waves
@@ -0,0 +1,142 @@
# Implementation Waves
**Generated:** 2026-03-30 14:58:37
This document outlines a cluster-based implementation plan for placeholder remediation.
## Overview
Total remediation effort: **82-110 hours** over 4-6 weeks
### Timeline
- **Wave 1 (P0):** Week 1 - Critical fixes (14-20 hours)
- **Wave 2 (P1):** Weeks 2-3 - High priority (26-34 hours)
- **Wave 3 (P2):** Weeks 4-5 - Medium priority (18-24 hours)
- **Wave 4 (P3):** Later - Nice to have (24-32 hours)
## Wave 1: Critical Fixes (P0)
**Scope:** 83 placeholders
**Timeline:** Week 1
**Effort:** 14-20 hours
### 1.1 Resolve Known Conflicts (3 placeholders, 2 hours)
- `weight_trend`: Update docs to match code (28d)
- `activity_summary`: Update docs to match code (14d)
- `activity_detail`: Needs code review to determine actual time window
### 1.2 Classify Time Windows (74 placeholders, 8-12 hours)
**Method:**
1. Name-based extraction (`*_7d`, `*_28d` patterns) - automatic
2. Code parameter extraction - semi-automatic
3. Manual classification for unclear cases
### 1.3 Add Categories and Descriptions (49 placeholders, 4-6 hours)
**Method:**
- Bulk update from audit semantic analysis
- Use provided classifications from audit report
## Wave 2: High Priority (P1)
**Scope:** 10 placeholders
**Timeline:** Weeks 2-3
**Effort:** 26-34 hours
### 2.1 Add Confidence Logic (11 trend/delta placeholders, 12-16 hours)
**Placeholders:**
- `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')`
### 2.2 Structured Missing-Value Policy (70 placeholders, 8-10 hours)
**Refactor:**
- Keep legacy string for backward compatibility
- Add structured fields: `available`, `missing_reason`, `value_raw`
### 2.3 Document Data Layer Modules (100 placeholders, 6-8 hours)
**Method:**
- Trace resolver functions to data layer
- Document source tables from SQL queries
## Wave 3: Medium Priority (P2)
**Scope:** 10 placeholders
**Timeline:** Weeks 4-5
**Effort:** 18-24 hours
### 3.1 Integrate Unused Placeholders (67 placeholders, 4-6 hours)
**Method:**
- Product management review for 30 planned placeholders
- Technical review for 37 plausible placeholders
- Create prompt use cases (5-10 quick wins)
### 3.2 Metadata Completeness (111 placeholders, 10-12 hours)
**Target:** Minimum 60% of placeholders with score >60
### 3.3 Production Status (20-30 core placeholders, 4-6 hours)
**Criteria:**
- Metadata completeness >= 80%
- Used-by >= 1
- No known issues
- Time window + confidence defined
## Wave 4: Nice to Have (P3)
**Scope:** 8 placeholders
**Timeline:** Later
**Effort:** 24-32 hours
### 4.1 Validation Framework (16-20 hours)
**Features:**
- Pre-commit hook for normative spec validation
- CI/CD consistency checks (code-catalog)
- Template generator for new placeholders
### 4.2 Migration Guides (8-12 hours)
**Content:**
- Best-practice guide (based on compliant examples)
- Anti-patterns to avoid
- Upgrade path for legacy prompts
## Dependencies
- **Wave 1 → Wave 2:** Time window classification must be complete before confidence logic
- **Wave 2 → Wave 3:** Data layer documentation enables better integration planning
- **Wave 3 → Wave 4:** Production-ready placeholders provide best-practice models
## Success Metrics
### After Wave 1:
- 0 unknown time windows
- 0 unknown categories
- 0 code-documentation conflicts
### After Wave 2:
- 70%+ placeholders with confidence logic
- 100% placeholders with structured missing-value policies
- 100% placeholders with documented data layers
### After Wave 3:
- 50-60% placeholder usage rate
- 60%+ placeholders with metadata completeness >60
- 20-30 production-ready placeholders
### After Wave 4:
- Automated validation in CI/CD
- Best-practice documentation for developers
- Sustainable maintenance process
@@ -0,0 +1,242 @@
# Placeholder Reconciliation Matrix
**Generated:** 2026-03-30 14:58:37
**Total Placeholders:** 111
## Statistics Summary
- **Exists in Code:** 71/111 (63%)
### Draft Status
- Full: 0
- Partial: 0
- Missing: 111
- Wrong: 0
### Compliance Level (from Audit)
- Compliant: 8 (7%)
- Partially Compliant: 22 (20%)
- Non-Compliant: 81 (73%)
### Reconciliation Status
- Verified Match: 7
- Needs Sharpening: 49
- Needs Refactor: 16
- Draft Wrong: 0
- New Required: 39
- Unclear: 0
### Confidence Distribution
- High: 10
- Medium: 49
- Low: 52
### Priority Distribution
- P0 (Critical): 83
- P1 (High): 10
- P2 (Medium): 10
- P3 (Low): 8
## Full Matrix
| # | Key | Exists | Draft | Category | Time Window | Used By | Compliance | Priority | Reconciliation | Action | Confidence | Notes |
|---|-----|--------|-------|----------|-------------|---------|------------|----------|----------------|--------|------------|-------|
| 1 | `ability_balance_coordination` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 2 | `ability_balance_endurance` | YES | missing | Training | unknown | 0 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 3 | `ability_balance_mental` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 4 | `ability_balance_mobility` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 5 | `ability_balance_strength` | YES | missing | Training | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 6 | `active_goals_json` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 7 | `active_goals_md` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 8 | `activity_detail` | YES | missing | Unknown | unknown | 4 | non_compliant | P0 | needs_refactor | code_change | high | Implementation exists but lacks documentation | Category needs classification | ... |
| 9 | `activity_score` | YES | missing | Scores (Phase 0b) | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 10 | `activity_summary` | YES | missing | Training | unknown | 2 | non_compliant | P0 | needs_refactor | code_change | high | Time window needs classification | Known conflict: Code uses 14d, docs say 7d | ... |
| 11 | `age` | YES | missing | Profil | latest | 2 | compliant | P3 | verified_match | no_change | high | Fully compliant with normative requirements | Draft specification missing for im... |
| 12 | `arm_28d_delta` | NO | missing | Unknown | 28d | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 13 | `bmi` | YES | missing | Körper | unknown | 0 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 14 | `body_progress_score` | YES | missing | Scores (Phase 0b) | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 15 | `caliper_summary` | YES | missing | Unknown | unknown | 8 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 16 | `carb_avg` | YES | missing | Ernährung | 30d | 2 | compliant | P3 | verified_match | no_change | high | Fully compliant with normative requirements | Draft specification missing for im... |
| 17 | `chest_28d_delta` | NO | missing | Unknown | 28d | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 18 | `circ_summary` | YES | missing | Unknown | mixed | 8 | compliant | P3 | verified_match | no_change | high | Fully compliant with normative requirements | High usage (8 references) - breaki... |
| 19 | `correlation_energy_weight_lag` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 20 | `correlation_load_hrv` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 21 | `correlation_load_rhr` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 22 | `correlation_protein_lbm` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 23 | `correlation_sleep_recovery` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 24 | `data_quality_score` | YES | missing | Scores (Phase 0b) | unknown | 0 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 25 | `datum_heute` | YES | missing | Zeitraum | unknown | 0 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 26 | `energy_balance_7d` | YES | missing | Ernährung | 7d | 1 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 27 | `energy_deficit_surplus` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 28 | `fat_avg` | YES | missing | Ernährung | 30d | 2 | compliant | P3 | verified_match | no_change | high | Fully compliant with normative requirements | Draft specification missing for im... |
| 29 | `fm_28d_change` | YES | missing | Körper | 28d | 1 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 30 | `focus_area_weights_json` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 31 | `focus_areas_weighted_json` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 32 | `focus_areas_weighted_md` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 33 | `focus_cat_aktivität_progress` | YES | missing | Focus Areas | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 34 | `focus_cat_aktivität_weight` | YES | missing | Focus Areas | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 35 | `focus_cat_ernährung_progress` | YES | missing | Focus Areas | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 36 | `focus_cat_ernährung_weight` | YES | missing | Focus Areas | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 37 | `focus_cat_körper_progress` | YES | missing | Focus Areas | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 38 | `focus_cat_körper_weight` | YES | missing | Focus Areas | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 39 | `focus_cat_lebensstil_progress` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 40 | `focus_cat_lebensstil_weight` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 41 | `focus_cat_mental_progress` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 42 | `focus_cat_mental_weight` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 43 | `focus_cat_recovery_progress` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 44 | `focus_cat_recovery_weight` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 45 | `focus_cat_vitalwerte_progress` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 46 | `focus_cat_vitalwerte_weight` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 47 | `geschlecht` | YES | missing | Profil | latest | 14 | non_compliant | P0 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | High usage (14 references) - breaking ch... |
| 48 | `goal_bf_pct` | YES | missing | Unknown | unknown | 10 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Implementation exists but lacks documentation | Category needs classification | ... |
| 49 | `goal_progress_score` | YES | missing | Scores (Phase 0b) | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 50 | `goal_weight` | YES | missing | Unknown | unknown | 8 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Implementation exists but lacks documentation | Category needs classification | ... |
| 51 | `height` | YES | missing | Profil | latest | 12 | non_compliant | P0 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | High usage (12 references) - breaking ch... |
| 52 | `hip_28d_delta` | NO | missing | Unknown | 28d | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 53 | `hrv_vs_baseline_pct` | YES | missing | Vitalwerte | unknown | 1 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 54 | `intake_volatility` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 55 | `kcal_avg` | YES | missing | Ernährung | 30d | 1 | compliant | P3 | verified_match | no_change | high | Fully compliant with normative requirements | Draft specification missing for im... |
| 56 | `kf_aktuell` | YES | missing | Körper | latest | 2 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 57 | `lbm_28d_change` | YES | missing | Körper | 28d | 1 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 58 | `macro_consistency_score` | YES | missing | Ernährung | unknown | 0 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 59 | `monotony_score` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 60 | `name` | YES | missing | Profil | latest | 19 | non_compliant | P0 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | High usage (19 references) - breaking ch... |
| 61 | `nutrition_days` | YES | missing | Unknown | unknown | 2 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Implementation exists but lacks documentation | Category needs classification | ... |
| 62 | `nutrition_score` | YES | missing | Scores (Phase 0b) | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 63 | `plateau_detected` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 64 | `protein_adequacy_28d` | YES | missing | Ernährung | 28d | 1 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 65 | `protein_avg` | YES | missing | Ernährung | 30d | 1 | compliant | P3 | verified_match | no_change | high | Fully compliant with normative requirements | Draft specification missing for im... |
| 66 | `protein_days_in_target` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 67 | `protein_g_per_kg` | YES | missing | Ernährung | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 68 | `protein_ziel_high` | YES | missing | Unknown | unknown | 7 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Implementation exists but lacks documentation | Category needs classification | ... |
| 69 | `protein_ziel_low` | YES | missing | Unknown | unknown | 7 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Implementation exists but lacks documentation | Category needs classification | ... |
| 70 | `proxy_internal_load_7d` | YES | missing | Training | 7d | 0 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 71 | `quality_sessions_pct` | YES | missing | Training | unknown | 1 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 72 | `recent_load_balance_3d` | NO | missing | Unknown | unknown | 0 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 73 | `recomposition_quadrant` | YES | missing | Körper | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 74 | `recovery_score` | YES | missing | Scores (Phase 0b) | unknown | 1 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 75 | `rest_day_compliance` | YES | missing | Training | unknown | 0 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 76 | `rest_days_count` | YES | missing | Schlaf & Erholung | unknown | 0 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 77 | `rhr_vs_baseline_pct` | YES | missing | Vitalwerte | unknown | 0 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 78 | `sleep_avg_duration` | YES | missing | Schlaf & Erholung | 30d | 0 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 79 | `sleep_avg_duration_7d` | YES | missing | Schlaf & Erholung | 7d | 1 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 80 | `sleep_avg_quality` | YES | missing | Schlaf & Erholung | 30d | 0 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 81 | `sleep_debt_hours` | YES | missing | Schlaf & Erholung | unknown | 0 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 82 | `sleep_quality_7d` | YES | missing | Schlaf & Erholung | 7d | 1 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 83 | `sleep_regularity_proxy` | YES | missing | Schlaf & Erholung | unknown | 0 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 84 | `strain_score` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 85 | `thigh_28d_delta` | NO | missing | Unknown | 28d | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 86 | `top_3_focus_areas` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 87 | `top_3_goals_behind_schedule` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 88 | `top_3_goals_on_track` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 89 | `top_drivers` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 90 | `top_focus_area_name` | YES | missing | Focus Areas | unknown | 0 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 91 | `top_focus_area_progress` | YES | missing | Focus Areas | unknown | 0 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 92 | `top_goal_name` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 93 | `top_goal_progress_pct` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 94 | `top_goal_status` | NO | missing | Unknown | unknown | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 95 | `training_frequency_7d` | YES | missing | Training | 7d | 0 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 96 | `training_minutes_week` | YES | missing | Training | 7d | 1 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 97 | `trainingstyp_verteilung` | YES | missing | Training | unknown | 0 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Time window needs classification | Draft specification missing for implemented f... |
| 98 | `vitals_avg_hr` | YES | missing | Vitalwerte | 30d | 0 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 99 | `vitals_avg_hrv` | YES | missing | Vitalwerte | 30d | 0 | partially_compliant | P1 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Draft specification missing for... |
| 100 | `vitals_vo2_max` | YES | missing | Vitalwerte | unknown | 0 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 101 | `vo2max_trend_28d` | YES | missing | Vitalwerte | 28d | 0 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 102 | `waist_28d_delta` | YES | missing | Körper | 28d | 0 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 103 | `waist_hip_ratio` | YES | missing | Körper | unknown | 0 | partially_compliant | P0 | needs_sharpening | metadata_only | medium | Partial compliance - needs metadata enrichment | Time window needs classificatio... |
| 104 | `weight_28d_slope` | YES | missing | Körper | 28d | 0 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 105 | `weight_7d_median` | YES | missing | Körper | 7d | 1 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 106 | `weight_90d_slope` | NO | missing | Unknown | 90d | 0 | non_compliant | P0 | new_required | build_new | low | Not implemented, needs build |
| 107 | `weight_aktuell` | YES | missing | Körper | latest | 10 | compliant | P3 | verified_match | no_change | high | Fully compliant with normative requirements | High usage (10 references) - break... |
| 108 | `weight_trend` | YES | missing | Körper | 28d | 10 | compliant | P3 | needs_refactor | code_change | high | Known conflict: Code uses 28d, docs say 7d/30d | Resolution: Update docs to matc... |
| 109 | `zeitraum_30d` | YES | missing | Zeitraum | 30d | 0 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 110 | `zeitraum_7d` | YES | missing | Zeitraum | 7d | 0 | non_compliant | P2 | needs_refactor | code_change | low | Code-docs conflicts or quality issues | Draft specification missing for implemen... |
| 111 | `zeitraum_90d` | YES | missing | Unknown | 90d | 0 | non_compliant | P0 | needs_sharpening | metadata_only | medium | Implementation exists but lacks documentation | Category needs classification | ... |
## Critical Placeholders (P0)
These placeholders require immediate attention:
- `name`: Code-docs conflicts or quality issues | High usage (19 references) - breaking change risk | Draft specification missing for implemented feature
- `geschlecht`: Code-docs conflicts or quality issues | High usage (14 references) - breaking change risk | Draft specification missing for implemented feature
- `height`: Code-docs conflicts or quality issues | High usage (12 references) - breaking change risk | Draft specification missing for implemented feature
- `goal_bf_pct`: Implementation exists but lacks documentation | Category needs classification | Description needs to be written | High usage (10 references) - breaking change risk | Draft specification missing for implemented feature
- `caliper_summary`: Partial compliance - needs metadata enrichment | Time window needs classification | High usage (8 references) - breaking change risk | Draft specification missing for implemented feature
- `goal_weight`: Implementation exists but lacks documentation | Category needs classification | Description needs to be written | High usage (8 references) - breaking change risk | Draft specification missing for implemented feature
- `protein_ziel_high`: Implementation exists but lacks documentation | Category needs classification | Description needs to be written | High usage (7 references) - breaking change risk | Draft specification missing for implemented feature
- `protein_ziel_low`: Implementation exists but lacks documentation | Category needs classification | Description needs to be written | High usage (7 references) - breaking change risk | Draft specification missing for implemented feature
- `activity_detail`: Implementation exists but lacks documentation | Category needs classification | Description needs to be written | Known conflict: Time window unclear in code | High usage (4 references) - breaking change risk | Draft specification missing for implemented feature
- `activity_summary`: Time window needs classification | Known conflict: Code uses 14d, docs say 7d | Draft specification missing for implemented feature
- `nutrition_days`: Implementation exists but lacks documentation | Category needs classification | Description needs to be written | Draft specification missing for implemented feature
- `ability_balance_strength`: Time window needs classification | Draft specification missing for implemented feature
- `activity_score`: Time window needs classification | Draft specification missing for implemented feature
- `body_progress_score`: Time window needs classification | Draft specification missing for implemented feature
- `focus_cat_aktivität_progress`: Time window needs classification | Draft specification missing for implemented feature
- `focus_cat_aktivität_weight`: Time window needs classification | Draft specification missing for implemented feature
- `focus_cat_ernährung_progress`: Time window needs classification | Draft specification missing for implemented feature
- `focus_cat_ernährung_weight`: Time window needs classification | Draft specification missing for implemented feature
- `focus_cat_körper_progress`: Time window needs classification | Draft specification missing for implemented feature
- `focus_cat_körper_weight`: Time window needs classification | Draft specification missing for implemented feature
- `goal_progress_score`: Time window needs classification | Draft specification missing for implemented feature
- `hrv_vs_baseline_pct`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `nutrition_score`: Time window needs classification | Draft specification missing for implemented feature
- `protein_g_per_kg`: Time window needs classification | Draft specification missing for implemented feature
- `quality_sessions_pct`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `recomposition_quadrant`: Time window needs classification | Draft specification missing for implemented feature
- `recovery_score`: Time window needs classification | Draft specification missing for implemented feature
- `ability_balance_coordination`: Not implemented, needs build
- `ability_balance_endurance`: Time window needs classification | Draft specification missing for implemented feature
- `ability_balance_mental`: Not implemented, needs build
- `ability_balance_mobility`: Not implemented, needs build
- `active_goals_json`: Not implemented, needs build
- `active_goals_md`: Not implemented, needs build
- `arm_28d_delta`: Not implemented, needs build
- `bmi`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `chest_28d_delta`: Not implemented, needs build
- `correlation_energy_weight_lag`: Not implemented, needs build
- `correlation_load_hrv`: Not implemented, needs build
- `correlation_load_rhr`: Not implemented, needs build
- `correlation_protein_lbm`: Not implemented, needs build
- `correlation_sleep_recovery`: Not implemented, needs build
- `data_quality_score`: Time window needs classification | Draft specification missing for implemented feature
- `datum_heute`: Time window needs classification | Draft specification missing for implemented feature
- `energy_deficit_surplus`: Not implemented, needs build
- `focus_area_weights_json`: Not implemented, needs build
- `focus_areas_weighted_json`: Not implemented, needs build
- `focus_areas_weighted_md`: Not implemented, needs build
- `focus_cat_lebensstil_progress`: Not implemented, needs build
- `focus_cat_lebensstil_weight`: Not implemented, needs build
- `focus_cat_mental_progress`: Not implemented, needs build
- `focus_cat_mental_weight`: Not implemented, needs build
- `focus_cat_recovery_progress`: Not implemented, needs build
- `focus_cat_recovery_weight`: Not implemented, needs build
- `focus_cat_vitalwerte_progress`: Not implemented, needs build
- `focus_cat_vitalwerte_weight`: Not implemented, needs build
- `hip_28d_delta`: Not implemented, needs build
- `intake_volatility`: Not implemented, needs build
- `macro_consistency_score`: Time window needs classification | Draft specification missing for implemented feature
- `monotony_score`: Not implemented, needs build
- `plateau_detected`: Not implemented, needs build
- `protein_days_in_target`: Not implemented, needs build
- `recent_load_balance_3d`: Partial compliance - needs metadata enrichment | Time window needs classification
- `rest_day_compliance`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `rest_days_count`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `rhr_vs_baseline_pct`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `sleep_debt_hours`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `sleep_regularity_proxy`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `strain_score`: Not implemented, needs build
- `thigh_28d_delta`: Not implemented, needs build
- `top_3_focus_areas`: Not implemented, needs build
- `top_3_goals_behind_schedule`: Not implemented, needs build
- `top_3_goals_on_track`: Not implemented, needs build
- `top_drivers`: Not implemented, needs build
- `top_focus_area_name`: Time window needs classification | Draft specification missing for implemented feature
- `top_focus_area_progress`: Time window needs classification | Draft specification missing for implemented feature
- `top_goal_name`: Not implemented, needs build
- `top_goal_progress_pct`: Not implemented, needs build
- `top_goal_status`: Not implemented, needs build
- `trainingstyp_verteilung`: Time window needs classification | Draft specification missing for implemented feature
- `vitals_vo2_max`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `waist_hip_ratio`: Partial compliance - needs metadata enrichment | Time window needs classification | Draft specification missing for implemented feature
- `weight_90d_slope`: Not implemented, needs build
- `zeitraum_90d`: Implementation exists but lacks documentation | Category needs classification | Description needs to be written | Draft specification missing for implemented feature
@@ -0,0 +1,254 @@
# Placeholder Reconciliation Report
**Generated:** 2026-03-30
**Scope:** 111 Placeholders
**Status:** COMPLETE ✓
## Overview
This reconciliation consolidates data from three authoritative sources to create a **single source of truth** for all 111 placeholders in the Mitai Jinkendo system.
### Data Sources
1. **Export Catalog** (`.claude/docs/audit/platzhalter/PLACEHOLDER_CATALOG_EXTENDED.json`)
- Authoritative placeholder metadata export
- Contains 111 placeholder definitions with categories, descriptions, time windows, usage data
2. **Audit Reports** (`audit-report-2026-03-29/`)
- Comprehensive compliance audit against normative requirements
- Identifies gaps, conflicts, and remediation priorities
- Classifies placeholders: 8 compliant, 22 partially compliant, 81 non-compliant
3. **Draft Document** (`.claude/docs/concepts/canonical_placeholder_requirements_draft.md`)
- Normative placeholder specifications (4895 lines)
- Currently: 0 placeholders documented (draft in progress)
## Reconciliation Results
### Completeness Validation
✅ **PASS** - All 111 placeholders successfully reconciled
- Export-Keys: 111
- Matrix-Keys: 111
- Differenz: 0
- Fehlende Keys: []
- Doppelte Keys: []
### Key Statistics
#### Implementation Status
- **Exists in Code:** 71/111 (63%)
- **Not Implemented:** 40/111 (36%)
#### Compliance Level (from Audit)
- **Compliant:** 8 (7%) - Production-ready
- **Partially Compliant:** 22 (19%) - Minor gaps
- **Non-Compliant:** 81 (73%) - Major gaps
#### Reconciliation Status
- **Verified Match (7):** Draft ↔ Export ↔ Audit align perfectly
- **Needs Sharpening (49):** Correct but incomplete metadata
- **Needs Refactor (16):** Code-docs conflicts exist
- **Draft Wrong (0):** Draft specification incorrect
- **New Required (39):** Not implemented, needs build
- **Unclear (0):** Manual review needed
#### Priority Distribution
- **P0 (Critical):** 83 (74%) - Immediate attention required
- **P1 (High):** 10 (9%) - Next sprint
- **P2 (Medium):** 10 (9%) - Later
- **P3 (Low):** 8 (7%) - Maintenance only
#### Confidence Distribution
- **High:** 10 (9%) - Reliable data
- **Medium:** 49 (44%) - Some uncertainty
- **Low:** 52 (46%) - Needs verification
## Generated Documents
### 1. RECONCILIATION_COMPLETENESS_CHECK.md
Validation proof that all 111 placeholders were processed.
### 2. PLACEHOLDER_RECONCILIATION_MATRIX.json (119 KB)
Machine-readable complete reconciliation data:
- Schema version: 1.0.0
- All 111 placeholders with:
- Implementation status
- Draft status
- Export metadata (category, description, time_window, usage)
- Audit findings (compliance, priority, confidence logic)
- Architecture verification
- Reconciliation status and recommended action
- Confidence level and notes
### 3. PLACEHOLDER_RECONCILIATION_MATRIX.md (32 KB)
Human-readable table format:
- Full matrix with 111 rows
- Statistics summary
- Critical placeholders (P0) section
### 4. EXECUTIVE_RECONCILIATION_SUMMARY.md (4.1 KB)
High-level findings and recommendations:
- Key findings and statistics
- Known code-documentation conflicts (3)
- High-usage placeholders (12 with breaking change risk)
- Immediate actions (P0) and sprint plan (P1/P2/P3)
### 5. DRAFT_CORRECTIONS_REQUIRED.md (11 KB)
Lists all placeholders needing draft specifications:
- Missing: 111 placeholders
- Partial: 0 placeholders
- Wrong: 0 placeholders
- Bulk update strategy and effort estimates
### 6. IMPLEMENTATION_WAVES.md (4.1 KB)
Cluster-based remediation plan:
- Wave 1 (P0): Week 1 - 14-20 hours
- Wave 2 (P1): Weeks 2-3 - 26-34 hours
- Wave 3 (P2): Weeks 4-5 - 18-24 hours
- Wave 4 (P3): Later - 24-32 hours
- Total: 82-110 hours over 4-6 weeks
## Critical Issues
### Known Code-Documentation Conflicts
1. **`weight_trend`** - Code uses 28d, docs say 7d/30d
- Resolution: Update docs to match code (28d)
2. **`activity_summary`** - Code uses 14d, docs say 7d
- Resolution: Update docs to match code (14d)
3. **`activity_detail`** - Time window unclear in code
- Resolution: Needs code review to determine actual time window
### High-Usage Placeholders (Breaking Change Risk)
12 placeholders with 4+ uses require careful handling:
| Placeholder | Uses | Compliance |
|-------------|------|------------|
| `name` | 19 | non_compliant |
| `geschlecht` | 14 | non_compliant |
| `height` | 12 | non_compliant |
| `weight_aktuell` | 10 | compliant ✓ |
| `weight_trend` | 10 | compliant ✓ |
| `goal_bf_pct` | 10 | non_compliant |
| `caliper_summary` | 8 | partially_compliant |
| `circ_summary` | 8 | compliant ✓ |
| `goal_weight` | 8 | non_compliant |
| `protein_ziel_low` | 7 | non_compliant |
| `protein_ziel_high` | 7 | non_compliant |
| `activity_detail` | 4 | non_compliant |
### Missing Documentation (P0)
- **49 placeholders** lack category classification
- **49 placeholders** lack descriptions
- **74 placeholders** have unknown time windows
## Recommended Actions
### Immediate (P0) - Week 1
1. **Resolve Known Conflicts** (3 placeholders, 2-4 hours)
- Update documentation to match code implementation
2. **Classify Time Windows** (74 placeholders, 8-12 hours)
- Use name-based extraction (`*_7d`, `*_28d` patterns)
- Extract from code default parameters
- Manual classification for unclear cases
3. **Add Categories and Descriptions** (49 placeholders, 4-6 hours)
- Bulk update from audit semantic analysis
- Use existing audit report classifications
**Total P0 Effort:** 14-20 hours
### Next Sprint (P1) - Weeks 2-3
1. **Add Confidence Logic** (103 placeholders, 12-16 hours)
2. **Document Data Layer Modules** (100 placeholders, 6-8 hours)
3. **Structured Missing-Value Policy** (70 placeholders, 8-10 hours)
**Total P1 Effort:** 26-34 hours
### Later (P2-P3) - Weeks 4-6
1. **Integrate Unused Placeholders** (67 placeholders, 4-6 hours)
2. **Metadata Completeness** (111 placeholders, 10-12 hours)
3. **Production Status** (20-30 core placeholders, 4-6 hours)
4. **Validation Framework** (16-20 hours)
**Total P2-P3 Effort:** 42-56 hours
## Best-Practice Models
### Compliant Placeholders (8 total)
These serve as best-practice models for all others:
**Nutrition Averages (4):**
- `protein_avg`, `kcal_avg`, `fat_avg`, `carb_avg`
- Pattern: 30d time window, calculate_confidence, nutrition_metrics.py
**Body Metrics (3):**
- `weight_aktuell` (latest pattern, body_metrics.py)
- `weight_trend` (28d trend, calculate_confidence) *has conflict*
- `circ_summary` (mixed time window, best-of-each pattern)
**Profile (1):**
- `age` (snapshot, no confidence needed)
## Architecture Verification
- **71 placeholders (63%)** exist in code with sound architecture
- **40 placeholders (36%)** not implemented, need build
- **0 placeholders** with fundamental architecture issues
All implemented placeholders have valid resolvers and data sources.
## Success Metrics
### After P0 Remediation (Week 1)
- 0 unknown time windows ✓
- 0 unknown categories ✓
- 0 code-documentation conflicts ✓
### After P1 Remediation (Weeks 2-3)
- 70%+ placeholders with confidence logic
- 100% placeholders with structured missing-value policies
- 100% placeholders with documented data layers
### After P2-P3 Remediation (Weeks 4-6)
- 50-60% placeholder usage rate
- 60%+ placeholders with metadata completeness >60
- 20-30 production-ready placeholders
## Conclusion
The reconciliation process successfully analyzed all 111 placeholders and created a comprehensive single source of truth. While only 7% are currently fully compliant with normative requirements, the systematic gaps are primarily **documentation-related rather than functional**.
All 111 placeholders are:
- ✅ Properly inventoried
- ✅ Categorized by compliance level
- ✅ Prioritized for remediation
- ✅ Mapped to implementation plan
With a structured 4-6 week remediation plan (82-110 hours), the system can reach **>60% normative conformity** and establish a sustainable maintenance process.
## Next Steps
1. **Review** this reconciliation with product/tech leads
2. **Prioritize** P0 items for Week 1 sprint
3. **Execute** systematic remediation following implementation waves
4. **Track** progress against success metrics
5. **Iterate** based on findings and feedback
---
**For Questions or Issues:**
- Reconciliation Data: `PLACEHOLDER_RECONCILIATION_MATRIX.json`
- Executive Summary: `EXECUTIVE_RECONCILIATION_SUMMARY.md`
- Implementation Plan: `IMPLEMENTATION_WAVES.md`
@@ -0,0 +1,14 @@
# Reconciliation Completeness Validation
## Vollstaendigkeitscheck
- Export-Keys: 111
- Matrix-Keys: 111
- Differenz: 0
- Fehlende Keys: []
- Doppelte Keys: []
## Status: PASS
## Details
All placeholders successfully reconciled. Matrix contains exactly 111 entries matching the export catalog.