shinkan-jinkendo/.claude/rules/IMPLEMENTATION_RULES.md

# Implementation Rules – Mitai Jinkendo

> **PFLICHTLEKTÜRE für Claude Code vor jeder Feature-Implementierung.**
> Diese Regeln sind verbindlich und dürfen nicht ohne explizite
> Genehmigung des Nutzers übersprungen werden.

---

## 1. Konzept-basierte Implementierung (MANDATORY)

### 1.1 Wann gilt dieser Prozess?

**PFLICHT bei:**
- Feature-Requests mit verlinktem Konzept/Spec-Dokument
- Gitea Issues mit "Konzept" Label
- User sagt "laut Konzept", "wie im Konzept beschrieben"
- Komplexe Features mit >3 Datenquellen oder >5 Funktionen
- Neue Chart-Endpoints mit spezifischen Anforderungen

**OPTIONAL bei:**
- Einfache Bugfixes (1-2 Zeilen)
- Triviale UI-Änderungen (Text, Farbe, Spacing)
- Code-Cleanup ohne Funktionsänderung

**Bei Unsicherheit:** Prozess anwenden. Lieber einmal zu viel als einmal zu wenig.

---

## 2. Der 5-Stufen-Prozess

### Stufe 1: Anforderungsanalyse (BEFORE ANY CODE)

```
□ Konzept/Spec-Dokument VOLLSTÄNDIG lesen
□ Pro Feature: Checkliste mit ALLEN geforderten Elementen erstellen
□ Datenquellen identifizieren (welche Tabellen, data_layer Funktionen)
□ Fehlende Funktionen dokumentieren (was muss neu gebaut werden)
□ Unklarheiten als Fragen dokumentieren
□ Gap-Analyse: Was existiert bereits? Was fehlt komplett?
```

**Output:** Anforderungs-Matrix (Tabelle oder Liste)

**Beispiel für E1 (Energiebilanz Chart):**
```
Gefordert im Konzept:
✓ Kalorienaufnahme täglich (nutrition_log.kcal)
✓ 7d Durchschnitt Aufnahme (berechnen)
✗ Trainingskalorien (activity_log.kcal) → FEHLT
✗ Gewichtstrend 7d geglättet (weight_log) → FEHLT
✗ Lagged comparison 3d/7d/14d → FEHLT
✓ TDEE geschätzt (Profile-basiert oder Formel)
✗ Energiebilanz als Balken → Chart-Typ ändern

Offene Fragen:
- Trainingskalorien: activity_log.kcal oder estimated_kcal?
- TDEE: Aus Profil oder Harris-Benedict berechnen?
- Lag-Korrelation: Pearson oder andere Methode?
```

### Stufe 2: Umsetzungskonzept erstellen

```
□ Backend: Welche Endpoints? Welche Parameter?
□ Backend: Welche data_layer Funktionen? (existierend + neu)
□ Backend: Welche Berechnungen? (Formeln dokumentieren)
□ Frontend: Welche Komponenten? Welche Chart-Typen?
□ Frontend: Welche API-Calls?
□ Dependencies: Müssen andere Module angepasst werden?
```

**Output:** Strukturiertes Umsetzungskonzept als Markdown

**Beispiel:**
```markdown
## E1: Energiebilanz Chart - Umsetzungskonzept

### Backend
**Endpoint:** `GET /api/charts/energy-balance?days=28`

**Datenquellen:**
- `nutrition_log` (kcal, date)
- `activity_log` (kcal, date) → aggregiert nach Tag
- `weight_log` (weight, date) → 7d gleitend

**Neue data_layer Funktionen:**
- `get_daily_training_calories(profile_id, days)` → Summe kcal pro Tag
- `get_weight_trend_7d(profile_id, days)` → 7d gleitender Durchschnitt
- `calculate_lag_correlation(energy_balance, weight_change, lag_days)` → Pearson

**Berechnungen:**
1. Energie-Bilanz = kcal_intake - (TDEE + training_kcal)
2. 7d avg intake = rolling_mean(kcal_intake, 7)
3. 7d avg bilanz = rolling_mean(bilanz, 7)
4. Lag-Korrelation: bilanz[t] vs. weight_change[t+3/7/14]

**Response Format:**
```json
{
  "chart_type": "mixed",  // Line + Bar kombiniert
  "data": {
    "labels": ["2026-01-01", ...],
    "datasets": [
      {"type": "line", "label": "Kalorien", "data": [...]},
      {"type": "line", "label": "7d Ø Kalorien", "data": [...]},
      {"type": "line", "label": "Training kcal", "data": [...]},
      {"type": "line", "label": "TDEE", "data": [...], "borderDash": [5,5]},
      {"type": "bar", "label": "Bilanz", "data": [...], "yAxisID": "y1"},
      {"type": "line", "label": "Gewicht (7d)", "data": [...], "yAxisID": "y2"}
    ]
  },
  "metadata": {
    "avg_intake": 2100,
    "avg_balance": -300,
    "weight_change_7d": -0.5,
    "lag_correlation": {
      "3d": 0.42,
      "7d": 0.68,
      "14d": 0.75
    }
  }
}
```

### Frontend
**Component:** `NutritionCharts.jsx` → `renderEnergyBalance()`

**Chart-Typ:** Recharts `ComposedChart` (Line + Bar kombiniert)

**API-Call:** `api.getEnergyBalanceChart(days)`

**Features:**
- Dual Y-Axis (links: kcal, rechts: kg)
- Legende mit Hover-Details
- Tooltips zeigen alle Werte
- Lag-Korrelation in Metadata-Box unter Chart
```

### Stufe 3: User-Approval einholen (MANDATORY)

```
□ Umsetzungskonzept dem User zeigen
□ Offene Fragen klären
□ Auf explizites OK warten
□ Bei Änderungswünschen: Konzept anpassen, erneut zeigen
```

**Niemals** mit der Implementierung beginnen ohne User-Approval!

### Stufe 4: Implementierung

```
□ Exakt nach genehmigtem Konzept implementieren
□ Niemals "ähnliches" bauen oder Abkürzungen nehmen
□ Bei unvorhergesehenen Problemen: User informieren, Konzept anpassen
□ Commits: Referenz zum Konzept im Commit-Message
```

**Commit-Message Format:**
```
feat: E1 Energiebilanz Chart (konzept-konform)

Backend:
- Neue data_layer Funktionen: get_daily_training_calories, get_weight_trend_7d
- Endpoint: /api/charts/energy-balance mit Lag-Korrelation
- Chart-Type: mixed (Line + Bar kombiniert)

Frontend:
- ComposedChart mit Dual Y-Axis (kcal + kg)
- Lag-Korrelation Metadata-Display

Konzept: .claude/docs/functional/mitai_jinkendo_konzept_diagramme_auswertungen_v2.md (E1)
```

### Stufe 5: Compliance-Check (BEFORE COMMIT)

```
□ Jedes Feature gegen Konzept prüfen (Checkliste abhaken)
□ Alle geforderten Elemente vorhanden?
□ Berechnungen korrekt nach Konzept?
□ Chart-Typ und Darstellung wie gefordert?
□ Metadata vollständig?
```

**Erst nach 100% Compliance: Commit + Push**

---

## 3. Warnsignale für Fehlverhalten

**Wenn der User sagt:**
- "Das steht aber im Konzept"
- "Es fehlt X" (nach Deploy)
- "Überprüfe das Konzept"
- "Das ist nicht wie gefordert"

**→ SOFORT STOPPEN**
- Konzept nochmal vollständig lesen
- Gap-Analyse machen: Was fehlt?
- Nachfragen, nicht raten
- Konzept-konform überarbeiten

---

## 4. Skill-Integration

Für komplexe Features (>10 Funktionen, >3 Module):

```bash
/implement-feature <feature-name> <konzept-datei>
```

Der Skill führt automatisch Stufe 1-3 aus und wartet auf Approval.

---

## 5. Ausnahmen

**Einzige erlaubte Ausnahme:**
User sagt explizit: "Ignoriere das Konzept" oder "Mach es anders als im Konzept"

**Alle anderen Fälle:** Prozess anwenden.

---

## 6. Eskalation bei Unklarheiten

**Bei Unklarheiten im Konzept:**

1. **Niemals raten oder "ähnliches" bauen**
2. **Immer nachfragen:**
   - "Im Konzept steht X, aber unklar ist Y. Wie soll ich vorgehen?"
   - "Option A oder Option B?"
3. **Warten auf Antwort**
4. **Konzept mit Antwort aktualisieren**

---

## Zusammenfassung: 5-Stufen-Checkliste

```
□ 1. Anforderungsanalyse (Konzept vollständig lesen, Checkliste erstellen)
□ 2. Umsetzungskonzept (Backend + Frontend + Datenquellen dokumentieren)
□ 3. User-Approval (Konzept zeigen, auf OK warten)
□ 4. Implementierung (Exakt nach Konzept, keine Abkürzungen)
□ 5. Compliance-Check (100% Checkliste abhaken vor Commit)
```

**Kein Schritt darf übersprungen werden.**