---
name: refactoring-planner
description: >-
  Strukturierte Refactoring-Planung mit Impact-Analyse und schrittweiser Umsetzung
  für große Codebases. Use when asked to "plan refactoring", "refactor module",
  "restructure code", "Refactoring planen", "Code umstrukturieren", "Migration planen",
  "technische Schulden abbauen", or when preparing a large code change that affects
  multiple files. Generates prioritized, test-secured refactoring plans with
  rollback strategies.
---

# Refactoring Planner Skill

Erstelle strukturierte, sichere Refactoring-Pläne für große Codebases. Jeder Plan folgt dem Prinzip: **Absichern → Analysieren → Planen → Umsetzen → Verifizieren**.

## Refactoring-Workflow

### Schritt 1: Scope definieren

Bevor du planst, kläre den Scope:

```
Was genau soll refactored werden?
├── Einzelne Datei/Klasse → Micro-Refactoring
├── Ein Modul/Feature → Modul-Refactoring
├── Architektur-Schicht → Layer-Refactoring
├── Querschnittsthema → Cross-Cutting Refactoring
└── Gesamtarchitektur → Strategisches Refactoring
```

Frage den Entwickler:
1. **Was** ist das Ziel? (Lesbarkeit, Performance, Erweiterbarkeit, Testbarkeit?)
2. **Warum jetzt?** (Blockiert Feature-Entwicklung? Bugs? Onboarding?)
3. **Zeitbudget?** (1 Tag, 1 Woche, 1 Sprint?)
4. **Risikotoleranz?** (Kann die App kurz instabil sein oder muss alles rückwärtskompatibel bleiben?)

### Schritt 2: Ist-Zustand dokumentieren

Erstelle eine präzise Beschreibung des aktuellen Zustands:

```markdown
## Ist-Zustand: [Modul/Feature-Name]

### Betroffene Dateien
- `src/services/UserService.ts` (342 LoC) — Hauptproblem: God Class
- `src/controllers/UserController.ts` (128 LoC) — zu viel Logik im Controller
- `src/models/User.ts` (89 LoC) — Mixed Concerns

### Aktuelle Probleme
1. [Problem] — [Auswirkung] — [Schweregrad]
2. ...

### Aktuelle Abhängigkeiten
- Wird importiert von: [Liste]
- Importiert selbst: [Liste]
- Externe APIs: [Liste]

### Bestehende Tests
- Unit Tests: [Anzahl] — Coverage: [%]
- Integration Tests: [Anzahl]
- E2E Tests: [Anzahl]
```

### Schritt 3: Soll-Zustand definieren

```markdown
## Soll-Zustand

### Zielarchitektur
[Mermaid-Diagramm oder Beschreibung]

### Design-Entscheidungen
1. [Entscheidung] — Begründung: [Warum]
2. ...

### Neue Dateistruktur
src/
├── services/
│   ├── UserService.ts        → UserAuthService.ts + UserProfileService.ts
│   └── UserValidation.ts     → NEU
├── repositories/
│   └── UserRepository.ts     → NEU (aus Service extrahiert)
└── types/
    └── user.types.ts          → NEU (Shared Types)
```

### Schritt 4: Impact-Analyse

**KRITISCH**: Vor jedem Refactoring die Auswirkungen analysieren:

```markdown
## Impact-Analyse

### Direkt betroffene Dateien
| Datei | Änderungstyp | Risiko |
|---|---|---|
| `UserService.ts` | Aufteilen | 🔴 Hoch |
| `UserController.ts` | Interface-Änderung | 🟡 Mittel |
| `user.routes.ts` | Import-Pfade | 🟢 Niedrig |

### Indirekt betroffene Dateien
[Alle Dateien die die betroffenen Module importieren]

### Breaking Changes
- [ ] API-Contracts ändern sich → Clients müssen angepasst werden
- [ ] Datenbank-Schema ändert sich → Migration nötig
- [ ] Konfiguration ändert sich → Deployment-Anpassung nötig
- [ ] Externe Integrationen betroffen

### Risiko-Bewertung
- Gesamtrisiko: [🔴 Hoch / 🟡 Mittel / 🟢 Niedrig]
- Begründung: [...]
- Rollback-Strategie: [...]
```

### Schritt 5: Refactoring-Plan erstellen

Nutze das Template in `./templates/refactoring-plan.md`.

Der Plan MUSS diese Eigenschaften haben:

1. **Atomare Schritte** — Jeder Schritt ist einzeln committbar und deploybar
2. **Tests zuerst** — Vor jeder Änderung Regression-Tests erstellen
3. **Rückwärtskompatibel** — Alte Interfaces bleiben erhalten bis alle Consumer migriert sind
4. **Verifizierbar** — Nach jedem Schritt: Tests grün? Build erfolgreich? App funktioniert?

### Schritt 6: Umsetzungs-Reihenfolge

Folge immer dem **Strangler Fig Pattern**:

```
Phase 1: Absichern
├── Fehlende Tests für bestehenden Code schreiben
├── Snapshot-Tests für kritische Outputs erstellen
└── CI/CD Pipeline sicherstellen

Phase 2: Parallel aufbauen
├── Neue Struktur neben der alten erstellen
├── Neue Tests für neue Struktur schreiben
└── Beide Versionen koexistieren lassen

Phase 3: Umleiten
├── Consumer schrittweise auf neue Struktur umleiten
├── Feature-Flags nutzen wenn möglich
└── Nach jeder Umleitung: Regression-Tests

Phase 4: Aufräumen
├── Alte Implementierung entfernen
├── Verwaiste Imports bereinigen
├── Dokumentation aktualisieren
└── Finale Test-Suite validieren
```

## Refactoring-Patterns (Referenz)

### Micro-Refactorings (einzelne Datei, < 1h)

| Pattern | Wann | Vorgehen |
|---|---|---|
| **Extract Method** | Funktion > 30 Zeilen | Logische Blöcke in eigene Funktionen |
| **Extract Interface** | Klasse hat zu viele Verantwortungen | Interface definieren, Implementierung separieren |
| **Replace Conditional with Polymorphism** | Lange if/switch-Ketten | Strategy Pattern einführen |
| **Introduce Parameter Object** | Funktion hat > 4 Parameter | DTO/Config-Objekt erstellen |
| **Remove Dead Code** | Ungenutzte Exports/Funktionen | `ts-prune` nutzen, dann entfernen |

### Modul-Refactorings (mehrere Dateien, 1-5 Tage)

| Pattern | Wann | Vorgehen |
|---|---|---|
| **Split God Class** | Klasse > 500 LoC, multiple Concerns | Nach Verantwortung aufteilen (SRP) |
| **Extract Service** | Controller enthält Geschäftslogik | Service Layer einführen |
| **Introduce Repository** | Datenbankzugriffe verstreut | Repository Pattern einführen |
| **Event-Driven Decoupling** | Tight Coupling zwischen Modulen | Events/Observer einführen |

### Architektur-Refactorings (viele Dateien, 1-4 Wochen)

| Pattern | Wann | Vorgehen |
|---|---|---|
| **Strangler Fig** | Legacy-System schrittweise ersetzen | Neue Implementierung parallel, schrittweise umleiten |
| **Branch by Abstraction** | Große Dependency ersetzen | Abstraktionsschicht einführen, dann austauschen |
| **Feature Flags** | Risikoreiche Änderungen | Beide Pfade parallel, per Flag steuerbar |

## Wichtige Regeln

1. **Nie Refactoring und Feature-Entwicklung in einem PR mischen**
2. **Jeden Refactoring-Schritt als eigenen Commit**
3. **Refactoring-PR sollte keine funktionalen Änderungen enthalten**
4. **Immer mit dem niedrigsten Risiko anfangen**
5. **Bei Unsicherheit: Kleinere Schritte wählen**
6. **Keine Optimierungen während des Refactorings** — erst strukturieren, dann optimieren