---
name: troubleshoot-host
description: Standardisierter Troubleshooting-Workflow für Host-Systeme in ~/Nextcloud/hosts/
invocation: /troubleshoot-host
---

# Host Troubleshooting Skill

Dieser Skill führt durch einen standardisierten Troubleshooting-Prozess für Systeme, die unter `~/Nextcloud/hosts/` dokumentiert sind.

## Voraussetzungen

- Du befindest dich in einem Host-Verzeichnis unter `~/Nextcloud/hosts/[kunde]/[hostname]/`
- Eine `copilot-instructions.md` existiert (oder wird erstellt)

## Workflow

### Phase 1: Kontext erfassen

1. **Verzeichnis prüfen**
   ```bash
   pwd
   ls -la
   ```

2. **Dokumentation laden**
   - Lies `copilot-instructions.md` falls vorhanden
   - Falls nicht vorhanden: Frage ob Template verwendet werden soll
   - Template-Pfad: `~/Nextcloud/hosts/_templates/copilot-instructions-template.md`

3. **System-Typ identifizieren**
   - Windows / Linux / Appliance
   - Zugangsart (SSH, RDP, API, Web)
   - Abhängigkeiten notieren

### Phase 2: Problem analysieren

Frage den User nach folgenden Informationen (falls nicht bereits bekannt):

| Frage | Zweck |
|-------|-------|
| Was ist das Symptom? | Genaue Fehlerbeschreibung |
| Wann trat es auf? | Zeitliche Eingrenzung |
| Was hat sich geändert? | Mögliche Ursachen identifizieren |
| Wer/was ist betroffen? | Scope verstehen |
| Gibt es Fehlermeldungen? | Konkrete Anhaltspunkte |

### Phase 3: Diagnose durchführen

1. **Quick Reference nutzen**
   - Führe die Basis-Checks aus der `copilot-instructions.md` durch
   - Nutze die dokumentierten Befehle

2. **Logs prüfen**
   - Konsultiere die Log-Locations aus der Doku
   - Suche nach Fehlern im relevanten Zeitraum

3. **Abhängigkeiten prüfen**
   - Sind verbundene Systeme erreichbar?
   - Funktionieren die Schnittstellen?

4. **Hypothesen bilden**
   - Liste mögliche Ursachen auf
   - Priorisiere nach Wahrscheinlichkeit

### Phase 4: Lösung implementieren

1. **Jeden Schritt dokumentieren**
   - Was wurde versucht?
   - Was war das Ergebnis?

2. **Fix anwenden**
   - Bei Unsicherheit: Backup/Snapshot zuerst
   - Änderungen minimal halten

3. **Verifizieren**
   - Symptom behoben?
   - Keine neuen Probleme?
   - Betroffene User informiert?

### Phase 5: Dokumentation aktualisieren

**WICHTIG:** Nach erfolgreicher Lösung MUSS die Dokumentation aktualisiert werden!

1. **Problem + Lösung eintragen**

   Füge in `copilot-instructions.md` unter "Bekannte Probleme & Lösungen" hinzu:

   ```markdown
   ### [Problem-Titel]

   **Symptom:** [Genaue Beschreibung]

   **Ursache:** [Was das Problem verursacht hat]

   **Lösung:**
   ```bash
   [Befehle oder Schritte]
   ```

   **Datum:** [YYYY-MM-DD] | **Commit:** `[HASH]`
   ```

2. **Weitere Erkenntnisse dokumentieren**
   - Neue Pitfalls?
   - Troubleshooting-Checkliste erweitern?
   - Abhängigkeiten aktualisieren?

3. **Git Commit**
   ```bash
   git add -A
   git commit -m "Troubleshooting: [Kurzbeschreibung des Problems/Lösung]"
   git push origin main  # falls Remote vorhanden
   ```

## Checkliste

- [ ] Dokumentation gelesen
- [ ] Problem verstanden
- [ ] Diagnose durchgeführt
- [ ] Lösung implementiert
- [ ] Fix verifiziert
- [ ] Dokumentation aktualisiert
- [ ] Git commit erstellt

## Tipps

### Wenn keine Doku existiert

1. Kopiere das Template:
   ```bash
   cp ~/Nextcloud/hosts/_templates/copilot-instructions-template.md ./copilot-instructions.md
   ```

2. Fülle während des Troubleshootings die relevanten Felder aus

3. Das Troubleshooting selbst liefert wertvolle Informationen für die Doku

### Bei komplexen Problemen

- Nutze die TodoWrite-Funktion um Schritte zu tracken
- Erstelle Hypothesen-Liste und arbeite sie systematisch ab
- Dokumentiere auch fehlgeschlagene Lösungsversuche (was NICHT funktioniert hat)

### Remote-Zugriff

Für SSH-Befehle auf dem Ziel-Host:
```bash
ssh user@host "befehl"
```

Für interaktive Sessions:
```bash
ssh user@host
# Dann Befehle ausführen
```

## Verwandte Skills

- `/session-end` - Am Ende der Session für Commit-Reminder
- `/new-project` - Falls neues Host-Verzeichnis angelegt werden muss