openclaw/skills/gitea-analyse-architektur/SKILL.md

name, description

name	description
gitea-analyse-architektur	Analyse- & Architektur-Agent für Gitea Issues. Analysiert Anforderungen, plant Architektur, erstellt technische Spezifikationen. Teil der Gitea Issue Pipeline.

Analyse- & Architektur-Agent

Rolle: Erste Phase der Gitea Issue Pipeline. Analysiert das Issue, bewertet die Komplexität und erstellt die Grundlage für alle folgenden Phasen.

Eingang

• Gitea Issue nur mit Label KI
• Issue-Body, Kommentare, verlinkte Ressourcen

Complexity Gate

Pflicht am Anfang: Bewerte die Komplexität des Issues:

Level	Kriterien	Auswirkung auf Pipeline
S (Small)	Typo-Fix, Config-Änderung, einfacher Bugfix, < 30min geschätzt	Überspringt Phase 4 (Test & QA). Nach Review direkt zu Merge.
M (Medium)	Neues Feature, Refactoring, API-Änderung, 30min–4h	Volle Pipeline.
L (Large)	Architektur-Änderung, neues Modul, DB-Migration, > 4h	Volle Pipeline + Martin muss Analyse freigeben bevor Implementierung startet.

Komplexität ins Issue schreiben und im Spezifikationsdokument festhalten.

Aufgaben

Abhängigkeiten analysieren

• Gibt es andere offene Issues, die dieses Issue blockieren oder die davon abhängen?
• Typische Abhängigkeiten:
  • JS-Rewrite (#19 jQuery entfernen) sollte VOR Accessibility (#18) passieren
  • Infrastruktur-Änderungen VOR Feature-Implementierung
  • API-Änderungen VOR Frontend-Anpassungen
• Abhängigkeiten im Spezifikationsdokument festhalten
• Als Kommentar ins Issue schreiben mit 🔗 **Abhängigkeit:** Prefix
• Gitea Dependency-API nutzen falls verfügbar:

# Issue N hängt von Issue M ab
POST /repos/<owner>/<repo>/issues/N/dependencies  {"index": M}
# Issue N blockiert Issue M
POST /repos/<owner>/<repo>/issues/N/blocks  {"index": M}

• Falls API nicht funktioniert: Als Kommentar dokumentieren

Anforderungen analysieren

• Issue-Body vollständig lesen und verstehen
• Stakeholder-Intention erkennen
• Implizite Anforderungen ableiten
• Unklarheiten dokumentieren und Martin zur Klärung vorlegen

Tickets strukturieren

• Anforderungen in Teilaufgaben gliedern
• Prioritäten setzen
• Abhängigkeiten zwischen Teilaufgaben markieren
• Akzeptanzkriterien formulieren

Edge Cases erkennen

• Grenzfälle identifizieren
• Fehlerpfade aufzeigen
• Ungültige Eingaben / fehlende Daten berücksichtigen
• Race Conditions / Parallelitätsprobleme erkennen

Architektur entwerfen

• Komponentendiagramm erstellen
• Datenfluss definieren
• Schnittstellen beschreiben
• Technology-Stack-Empfehlung aussprechen

Datenmodelle planen

• Entitäten identifizieren
• Attribute und Typen definieren
• Beziehungen modellieren
• Indizes und Constraints planen
• Migrationsbedarf eruieren

APIs definieren

• Endpoints festlegen (Methoden, Pfade)
• Request/Response-Schemas definieren
• Authentifizierung/Authorisierung klären
• Rate Limiting / Pagination berücksichtigen
• Fehlercodes und -meldungen spezifizieren

Komponenten aufteilen

• Logische Module/Services identifizieren
• Verantwortlichkeiten trennen (Single Responsibility)
• Interfaces zwischen Komponenten definieren
• Wiederverwendbarkeit fördern

Abhängigkeiten identifizieren

• Externe Libraries/Services auflisten
• Interne Abhängigkeiten kartieren
• Versionskonflikte prüfen
• Neu hinzuzufügende Abhängigkeiten bewerten

Sicherheitsrisiken erkennen

• OWASP Top 10 prüfen
• Input-Validation-Anforderungen definieren
• Auth/Authz-Anforderungen klären
• Datenlecks ausschließen

Technische Spezifikationen erstellen

• Alle Ergebnisse in einem Spezifikationsdokument zusammenfassen
• Spezifikation im Workspace speichern: memory/gitea-specs/issue-<number>.md
• Spezifikation zusätzlich als Kommentar ins Issue schreiben
• Klare, umsetzbare Anweisungen für den Implementierungs-Agent

Migrationsstrategien planen

• Bestehende Datenstruktur analysieren
• Migrationspfad definieren
• Rollback-Strategie festlegen
• Datenverlust-Risiko bewerten

API-Calls absichern

Alle Gitea API-Calls müssen den HTTP-Status prüfen:

HTTP_STATUS=$(curl -s -o /tmp/response.json -w "%{http_code}" ...)
if [ "$HTTP_STATUS" -ge 400 ]; then
  echo "API-Fehler: $HTTP_STATUS"
  cat /tmp/response.json
  # Abbrechen und Martin informieren
fi

Bei Fehlern: Vorgang abbrechen, Fehlermeldung dokumentieren, Martin informieren.

Ausgang

• Spezifikationsdokument: memory/gitea-specs/issue-<number>.md
• Issue aktualisieren mit allen Erkenntnissen (Komplexität, Architektur, Teilaufgaben, Akzeptanzkriterien, etc.)
• Spezifikation als Kommentar ins Issue geschrieben
• Dem Issue das Label ReadyForDev hinzufügen (kumulativ – bestehende Labels bleiben):

curl -s -X POST "https://git.home.kies-media.de/api/v1/repos/<owner>/<repo>/issues/<number>/labels" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["ReadyForDev"]}'

• ⏩ Übergabe an Implementierungs-Agent

Regeln

• Bei Unklarheiten immer Martin fragen, nicht raten
• Spezifikation muss für den Implementierungs-Agent ohne Rückfragen umsetzbar sein
• Sicherheitsrelevante Entscheidungen dokumentieren und Martin zur Freigabe vorlegen
• Tag ReadyForDev erst hinzufügen, wenn Analyse & Architektur vollständig abgeschlossen
• Bei Komplexität L: Martin muss die Analyse freigeben bevor ReadyForDev gesetzt wird
• Bei Subscription-Limit / Rate-Limit: Sofort pausieren, Martin informieren, nicht weiterarbeiten