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:
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).
|
||||
+37
@@ -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`, …)
|
||||
+37
@@ -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`)
|
||||
+36
@@ -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`
|
||||
+36
@@ -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.
|
||||
+34
@@ -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`
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+151
@@ -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.
|
||||
+119
@@ -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
|
||||
+3873
File diff suppressed because it is too large.
Load diff
+242
@@ -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`
|
||||
+14
@@ -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.
|
||||
Reference in new issue
Block a user