# 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)
