# Dokumentations-Bereinigung & Struktur-Konzept

**Erstellt:** 2026-03-23
**Ziel:** Redundanzen entfernen, klare Trennung zwischen Gitea (Tracking) und Docs (Spezifikationen)

---

## Problem-Analyse

### Aktuelle Situation

**Planungs-/Tracking-Dokumente (.claude/docs/):**
- `BACKLOG.md` (~138 Zeilen) - Feature-Übersicht v9c-v9h
- `ROADMAP.md` (~414 Zeilen) - Detaillierte Phasenplanung (Phase 0-3, Issues #24-#30)
- `KNOWN_ISSUES.md` (~100+ Zeilen) - Bug-Tracking (BUG-009, BUG-003, etc.)
- `PENDING_FEATURES.md` (~50+ Zeilen) - Feature-Enforcement-TODOs
- `TODO_V9D_PHASE2.md` - Spezifische Phase-2-TODOs
- `ISSUES_TO_CREATE.md` - Temporär (Issues bereits erstellt)
- `.claude/feature-requests/logout-button-header.md` - Einzelner Feature Request

**Spezifikationen:**
- `functional/` - SLEEP_MODULE.md, TRAINING_TYPES.md, DEVELOPMENT_ROUTES.md, etc.
- `technical/` - MEMBERSHIP_SYSTEM.md, DATABASE.md, ARCHITECTURE.md, etc.
- `architecture/` - FEATURE_ENFORCEMENT.md
- `rules/` - ARCHITECTURE.md, CODING_RULES.md, LESSONS_LEARNED.md

### Redundanzen & Probleme

1. **Doppeltes Tracking:**
   - ROADMAP.md enthält Issues #24-#30
   - Diese sollten primär in Gitea sein
   - ROADMAP.md enthält außerdem strategische Planung (Phase 0-3)

2. **Bug-Tracking außerhalb Gitea:**
   - KNOWN_ISSUES.md dokumentiert Bugs
   - BUG-009 ist offen, sollte als Gitea-Issue existieren

3. **Feature-Requests verstreut:**
   - BACKLOG.md listet große Features
   - PENDING_FEATURES.md listet TODOs
   - .claude/feature-requests/ hat einzelne Requests
   - Unklare Prioritäten

4. **TODOs ohne Kontext:**
   - TODO_V9D_PHASE2.md ist phasenspezifisch
   - Nach Phase-Abschluss veraltet

5. **Temporäre Dateien:**
   - ISSUES_TO_CREATE.md (bereits erledigt, kann weg)

---

## Vorgeschlagene Struktur

### Prinzip: Gitea für Tracking, Docs für Spezifikationen

```
┌─────────────────────────────────────────────────────────────┐
│ GITEA ISSUES                                                 │
│ (Primäres Tracking für Tasks, Bugs, kleine Features)        │
├─────────────────────────────────────────────────────────────┤
│ - Konkrete implementierbare Tasks                           │
│ - Bugs (BUG-001, BUG-002, ...)                             │
│ - Kleine Features (≤ 1 Tag Aufwand)                        │
│ - Phase-Tasks (#24-#30)                                     │
│ - Technical Debt (#32-#35)                                  │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ .claude/docs/functional/                                     │
│ (Fachliche Spezifikationen für große Features)              │
├─────────────────────────────────────────────────────────────┤
│ - SLEEP_MODULE.md (v9d)                                     │
│ - TRAINING_TYPES.md (v9d)                                   │
│ - DEVELOPMENT_ROUTES.md (v9e)                               │
│ - MEDITATION.md (v9g)                                       │
│ - AI_PROMPTS.md (v9f)                                       │
│ - GOALS_VITALS.md (v9f)                                     │
│ - RESPONSIVE_UI.md                                          │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ .claude/docs/technical/                                      │
│ (Technische Spezifikationen & Referenz-Dokumentation)       │
├─────────────────────────────────────────────────────────────┤
│ - ARCHITECTURE.md (System-Übersicht)                        │
│ - FRONTEND.md (Seiten, Komponenten, API-Integration)       │
│ - AUTH.md (Auth-Flow, Sicherheit)                          │
│ - API_REFERENCE.md (Alle Endpoints)                        │
│ - DATABASE.md (Schema, Tabellen)                           │
│ - MEMBERSHIP_SYSTEM.md (v9c Membership)                    │
│ - MIGRATIONS.md (falls vorhanden)                          │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ .claude/docs/ (Root-Level Meta-Dokumentation)               │
├─────────────────────────────────────────────────────────────┤
│ - README.md (Dokumentations-Index + Konventionen)          │
│ - CONTRIBUTING.md (Entwickler-Onboarding)                  │
│ - CHANGELOG.md (Versions-Historie, generiert aus git)      │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ .claude/rules/                                               │
│ (Verbindliche Entwicklungsregeln)                           │
├─────────────────────────────────────────────────────────────┤
│ - ARCHITECTURE.md (Architektur-Regeln, Versionierung)      │
│ - CODING_RULES.md (Code-Standards)                         │
│ - LESSONS_LEARNED.md (Fehler, die nicht wiederholt werden) │
└─────────────────────────────────────────────────────────────┘
```

---

## Konkrete Bereinigungsaktionen

### 1. LÖSCHEN (Redundant oder temporär)

| Datei | Grund | Aktion |
|-------|-------|--------|
| `ISSUES_TO_CREATE.md` | Temporär, Issues bereits erstellt (#32-#35) | **DELETE** |
| `TODO_V9D_PHASE2.md` | Phasenspezifisch, veraltet nach Abschluss | **DELETE** (oder archivieren) |
| `.claude/feature-requests/logout-button-header.md` | Einzelner Request, gehört in Gitea | **→ Gitea Issue, dann DELETE** |

### 2. MIGRIEREN zu Gitea Issues

| Quelle | Inhalt | Ziel-Aktion |
|--------|--------|-------------|
| `KNOWN_ISSUES.md` | BUG-009 (offen) | **→ Gitea Issue #36** (Bug) |
| `KNOWN_ISSUES.md` | BUG-003 (behoben) | **→ Archiv oder DELETE** (bereits behoben) |
| `PENDING_FEATURES.md` | Feature-Enforcement TODOs | **→ Gitea Issues #37-#39** (enhancement) |
| `feature-requests/logout-button-header.md` | Logout-Button Request | **→ Gitea Issue #40** (Quick Win) |

### 3. KONSOLIDIEREN

#### 3.1. ROADMAP.md → Aufteilen

**Problem:** Enthält sowohl strategische Planung als auch konkrete Issues

**Lösung:**

**BEHALTEN in ROADMAP.md (strategisch):**
- Phase-Übersicht (Phase 0-3)
- Meilensteine (M0.1-M3.x)
- Abhängigkeiten-Graph
- Timeline (KW-Planung)
- Risiken & Mitigationen
- Erfolgsmetriken

**MIGRIEREN zu Gitea (operativ):**
- Konkrete Issue-Beschreibungen (#24-#30) → Gitea Issues (bereits vorhanden?)
- Aufwands-Schätzungen → in Gitea Issue-Feldern
- Checklisten → in Gitea Issue-Beschreibungen

**RESULTAT:** ROADMAP.md wird zum strategischen Phasenplan (ohne Issue-Details)

#### 3.2. BACKLOG.md → Reduzieren

**Problem:** Mischung aus Feature-Übersicht und TODO-Listen

**Lösung:**

**BEHALTEN in BACKLOG.md:**
- Version-Übersicht (v9c-v9h Features)
- Links zu functional/-Specs
- Status-Übersicht (✅ KOMPLETT, 🟡 In Arbeit, 🔲 Geplant)

**ENTFERNEN aus BACKLOG.md:**
- Detaillierte Checklisten (gehören in Gitea Issues)
- "Offene Issues" Listen (primär in Gitea)
- Quick Wins (→ Gitea mit Label "quick-win")

**RESULTAT:** BACKLOG.md wird zum Feature-Katalog (Verweis auf Specs + Gitea)

#### 3.3. KNOWN_ISSUES.md → Archivieren oder löschen

**Vorschlag 1 (empfohlen):** DELETE
- Aktive Bugs → Gitea Issues
- Behobene Bugs → git commit messages + CHANGELOG.md
- Lessons Learned → `.claude/rules/LESSONS_LEARNED.md`

**Vorschlag 2:** Archivieren
- Umbenennen zu `KNOWN_ISSUES_ARCHIVE.md`
- Nur für Referenz (nicht aktiv gepflegt)

#### 3.4. PENDING_FEATURES.md → DELETE

**Grund:** Feature-Enforcement-TODOs sind konkrete Tasks

**Aktion:**
1. TODOs in Gitea Issues überführen (#37-#39)
2. Datei löschen

---

## Gitea Issues erstellen (aus existierenden Docs)

### Aus KNOWN_ISSUES.md

**#36: BUG-009 - Trainingstyp-Erstellung führt zu Internal Server Error**
- Priorität: High
- Label: bug, admin
- Aufwand: 1-2h

### Aus PENDING_FEATURES.md

**#37: Feature-Enforcement für Activity CSV-Import**
- Priorität: Medium
- Label: enhancement, feature-enforcement
- Aufwand: 2-3h

**#38: Feature-Enforcement für Nutrition CSV-Import UI**
- Priorität: Low
- Label: enhancement, feature-enforcement, ui
- Aufwand: 1h

**#39: Usage-Badges im Dashboard-Assistenten**
- Priorität: Low
- Label: enhancement, ux
- Aufwand: 1-2h

### Aus feature-requests/

**#40: Logout-Button im App-Header (neben Avatar)**
- Priorität: Low
- Label: quick-win, ux
- Aufwand: 15min

---

## Vorgeschlagene Konventionen

### Was gehört in Gitea Issues?

✅ **JA:**
- Bugs (alle Prioritäten)
- Konkrete implementierbare Tasks (≤ 5 Tage Aufwand)
- Quick Wins (≤ 1h Aufwand)
- Technical Debt Items
- Phase-spezifische Tasks (#24-#30)
- Refactorings

❌ **NEIN:**
- Große Feature-Pakete (v9e, v9f, v9g) → bleiben in functional/-Specs
- Strategische Planung (Phasen, Meilensteine) → bleibt in ROADMAP.md
- Architektur-Entscheidungen → bleiben in technical/-Docs
- Lessons Learned → bleiben in rules/LESSONS_LEARNED.md

### Was gehört in functional/-Specs?

✅ **Große Feature-Pakete (> 5 Tage Aufwand):**
- SLEEP_MODULE.md (v9d Phase 2b)
- TRAINING_TYPES.md (v9d Phase 1)
- DEVELOPMENT_ROUTES.md (v9e)
- AI_PROMPTS.md (v9f)
- MEDITATION.md (v9g)

**Format:**
- Fachliche Anforderungen (WAS wird gebaut)
- User Stories
- Use Cases
- Datenmodell (Konzept)
- UI-Mockups (optional)
- Verweis auf Gitea Epic/Milestone

### Was gehört in technical/-Specs?

✅ **Referenz-Dokumentation & Implementierungsdetails:**
- ARCHITECTURE.md (System-Übersicht)
- DATABASE.md (Schema-Referenz)
- API_REFERENCE.md (Endpoint-Katalog)
- Modul-spezifische Docs (MEMBERSHIP_SYSTEM.md)

**Format:**
- Technische Entscheidungen (WIE wird es gebaut)
- API-Spezifikationen
- Datenbank-Schema
- Code-Beispiele
- Design-Patterns

---

## Migrations-Plan

### Phase 1: Gitea Issues erstellen (1h)

1. **BUG-009** → Gitea Issue #36
2. **PENDING_FEATURES TODOs** → Gitea Issues #37-#39
3. **Logout-Button Request** → Gitea Issue #40

### Phase 2: Dokumentation bereinigen (30min)

1. **DELETE:**
   - `ISSUES_TO_CREATE.md`
   - `TODO_V9D_PHASE2.md`
   - `.claude/feature-requests/logout-button-header.md`
   - `KNOWN_ISSUES.md`
   - `PENDING_FEATURES.md`

2. **KONSOLIDIEREN:**
   - `ROADMAP.md` → Entferne Issue-Details, behalte Strategie
   - `BACKLOG.md` → Entferne Checklisten, behalte Feature-Katalog

### Phase 3: README.md erstellen (30min)

**Datei:** `.claude/docs/README.md`

**Inhalt:**
- Dokumentations-Index (Was finde ich wo?)
- Konventionen (Gitea vs. Docs)
- Wie lege ich Issues an?
- Wie erstelle ich Spezifikationen?

---

## Ergebnis nach Bereinigung

### Datei-Reduktion

**Vorher:**
- 7 Tracking-Dokumente (.claude/docs/)
- 1 Feature-Request-Datei
- ~700+ Zeilen redundante Informationen

**Nachher:**
- 2 Meta-Dokumente (ROADMAP.md, BACKLOG.md) - deutlich schlanker
- 1 README.md (Dokumentations-Index)
- ~5-7 Gitea Issues (primäres Tracking)

### Klare Trennung

```
Gitea Issues (Tracking)
  ↓
  Konkrete Tasks, Bugs, Quick Wins
  Labels: bug, enhancement, quick-win
  Aufwand: ≤ 5 Tage

.claude/docs/functional/ (Spezifikationen)
  ↓
  Große Feature-Pakete (> 5 Tage)
  Format: Fachliche Anforderungen
  Verweis auf Gitea Epic/Milestone

.claude/docs/technical/ (Referenz)
  ↓
  Implementierungsdetails
  Format: Technische Spezifikationen
  Generiert/aktualisiert nach Implementierung

.claude/rules/ (Regeln)
  ↓
  Verbindliche Entwicklungsstandards
  Format: Architektur-Regeln, Code-Standards
```

---

## Nächste Schritte

1. **Review:** User-Zustimmung zu diesem Plan einholen
2. **Gitea:** Issues #36-#40 anlegen
3. **Cleanup:** Dateien löschen/konsolidieren
4. **README:** `.claude/docs/README.md` erstellen
5. **ROADMAP/BACKLOG:** Kürzen auf strategische Infos
6. **Commit:** "docs: cleanup and consolidate documentation structure"

---

**Frage an User:**
- Sollen große Feature-Pakete (v9e, v9f, v9g) als Gitea **Milestones** angelegt werden?
  - Pro: Alle Tasks/Issues zuordenbar
  - Contra: Specs bleiben trotzdem in functional/
  - **Empfehlung:** Ja, Milestones in Gitea + Verweis in functional/-Specs