claude_settings/skills/troubleshoot-host.md

name, description, invocation

name	description	invocation
troubleshoot-host	Standardisierter Troubleshooting-Workflow für Host-Systeme in ~/Nextcloud/hosts/	/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

   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:

   ### [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

   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:

   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:

ssh user@host "befehl"

Für interaktive Sessions:

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