mitai-jinkendo/.claude/docs/CLEANUP_PLAN.md

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