From d27a389f0ed15c620c1fc7f742ffcbfd356f2b15 Mon Sep 17 00:00:00 2001 From: Gulum Date: Mon, 22 Jun 2026 21:07:04 +0200 Subject: [PATCH] =?UTF-8?q?feat(skill):=20ticket-triage=20=E2=80=94=20Fehl?= =?UTF-8?q?erberichte=20automatisiert=20abarbeiten?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Skill kapselt den erprobten Ablauf: Tickets aus /feedback holen, nach Status einteilen (Open/Answered = KI dran, NeedsInfo/Resolved überspringen), je Ticket ein Triage-Subagent (Workflow-Fan-out) mit strukturierter Empfehlung + Cluster, Rückfragen via PUT question (→ NeedsInfo) anhängen, beantwortete Tickets wieder aufgreifen, Fixes gebündelt nach datei-disjunkten Clustern umsetzen, Import neu einspielen und Tickets MIT fixNote (verständlicher Changelog) auf Resolved setzen. Co-Authored-By: Claude Opus 4.8 --- .claude/skills/ticket-triage/SKILL.md | 109 ++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 .claude/skills/ticket-triage/SKILL.md diff --git a/.claude/skills/ticket-triage/SKILL.md b/.claude/skills/ticket-triage/SKILL.md new file mode 100644 index 0000000..d396abe --- /dev/null +++ b/.claude/skills/ticket-triage/SKILL.md @@ -0,0 +1,109 @@ +--- +name: ticket-triage +description: >- + Fehlerberichte (Tickets) der Züchterin abarbeiten: neue Tickets per Subagent + triagieren, Rückfragen an die Tickets hängen, beantwortete Tickets wieder + aufgreifen, Fixes gebündelt umsetzen und beim Schließen dokumentieren, was + gefixt wurde. Nutze diesen Skill, wenn der Nutzer „Tickets abarbeiten / + triagieren", „Fehlerberichte bearbeiten" o. Ä. verlangt. +--- + +# Ticket-Triage & Abarbeitung + +Tickets entstehen über das „Fehler melden"-Feature (`POST /feedback`) und werden +unter **Hilfe → Meine Tickets** (`/hilfe/tickets`) verwaltet. Dieser Skill +automatisiert das Triagieren, Rückfragen-Stellen, Umsetzen und Schließen. + +## Status-Lebenszyklus (Feedback.Status) + +| Status | Bedeutung | Wer ist dran | +|---|---|---| +| `Open` | Neues Ticket, noch nicht triagiert | **KI** (triagieren) | +| `NeedsInfo` | KI hat eine **Rückfrage** angehängt | Züchterin (antworten) | +| `Answered` | Züchterin hat geantwortet | **KI** (wieder aufgreifen, umsetzen) | +| `Resolved` | Erledigt — mit `fixNote` (Changelog) | — | + +**Zu bearbeiten sind `Open` (neu) und `Answered` (KI wieder dran).** `NeedsInfo` +wartet auf die Züchterin, `Resolved` ist fertig — beide überspringen. + +## Voraussetzungen + +- App läuft (Aspire): `dotnet run --project GerbilManager.AppHost`; API auf + http://localhost:5179. Siehe `CLAUDE.md` (Architektur, Import→DB-Workflow, + Domänenwissen: 6-Jahre-Lebensspanne, Geschwisterverpaarung, Genotyp/E-Locus, + `isResident`). +- Feedback überlebt den Import-Ingest (FK-freie Spalten) — Tickets bleiben + erhalten, auch wenn die DB neu befüllt wird. + +## Ablauf + +### 1. Tickets holen & einteilen +`curl -s http://localhost:5179/feedback` (neueste zuerst). Encoding-Falle: über +eine Datei holen (`curl -o raw.json`) und mit `python … .decode('utf-8')` lesen, +nicht via Windows-stdin-Pipe (sonst Mojibake). Test-/Dummy-Tickets ausschließen. +Filtere auf `status in (Open, Answered)`. Bei `Answered` zusätzlich das Feld +`answer` (Antwort der Züchterin) mitnehmen — darauf basiert die Umsetzung. + +### 2. Triage per Subagent (ein Agent pro Ticket) +Nutze die **Workflow-Orchestrierung** (`pipeline`) — einen Triage-Agenten pro +Ticket. args ASCII-sicher halten (nur id/context/gerbilId/litterId übergeben; die +deutschen Nachrichten holt der Agent selbst aus `GET /feedback`). Defensive im +Script: `const tickets = Array.isArray(args) ? args : JSON.parse(args)`. + +Jeder Triage-Agent: +1. liest `CLAUDE.md` + `docs/ticket-triage.md` (falls vorhanden), +2. holt seinen Ticket-Text (+ `answer` bei `Answered`) aus `GET /feedback`, +3. untersucht die echten Daten über die API (`GET /gerbils/{id}`, `/litters/{id}`, + Eltern verfolgen; `provenance` zeigt Import-Herkunft inkl. verworfener Werte), +4. liefert strukturiert (StructuredOutput-Schema): `ticketId, title, category, + rootCause, recommendation, fixLayer (import-data|import-logic|backend|frontend| + genetics-engine), affectedAreas[], overlapKey (Cluster-Slug), effort (S/M/L), + confidence, needsUserInfo`. + +Sammle alle Ergebnisse in **eine Datei** `docs/ticket-triage.md` (Cluster-/ +Überschneidungs-Matrix + offene Rückfragen) — token-schonend per Python aus dem +Workflow-Ergebnis generieren, nicht 70 KB in den Kontext laden. + +### 3. Rückfragen an die Tickets hängen +Für jedes Ticket mit `needsUserInfo`: +`PUT /feedback/{id}` mit `{"question": ""}` → Status +wird automatisch `NeedsInfo`. Die Züchterin beantwortet es in der App; beim +nächsten Lauf taucht es als `Answered` auf und wird wieder aufgegriffen. + +### 4. Umsetzen — gebündelt nach Cluster (Überschneidungen vermeiden!) +Die Triage-Matrix zeigt, welche Tickets sich Dateien teilen. Bündele nach +**datei-disjunkten Workstreams**, damit parallele Subagenten nicht kollidieren: +- **Genetik-Engine** → `gerbil-manager-web/src/genetics/**`, `tools/import/genotype.py`. +- **Stammbaum-Import** (Eltern/Dedup/Gender/`isResident`) → `tools/import/extract.py`, + `merge_and_resolve.py`, `conflict-decisions.json`. +- **Frontend-Anzeige** (z. B. Nicht-Bestandstiere ausblenden) → `GerbilDetailPage.tsx`, + `de.ts`. +Gemeinsam genutzte Dateien (`de.ts`, `GerbilDetailPage.tsx`) gehören **genau einem** +Workstream — sonst sequenziell. Datenkorrekturen, die die Züchterin nennt, als +Override in `conflict-decisions.json` kodieren (data-driven, re-ingest-stabil). +Subagenten committen NICHT und re-ingesten NICHT — das koordiniert der Haupt-Loop. + +### 5. Import neu einspielen (bei Daten-/Import-Änderungen) +`python tools/import/extract.py` → `extract_contracts.py` → `merge_and_resolve.py`, +dann `POST /import/ingest-resolved` (wischt + lädt neu). Danach betroffene Tickets +gegen die API verifizieren. + +### 6. Ticket schließen — MIT Changelog +Beim Schließen IMMER dokumentieren, **was gefixt wurde**, in einfacher Sprache für +die Züchterin: +`PUT /feedback/{id}` mit `{"status": "Resolved", "fixNote": ""}`. +Beispiel: „Die Mutter von Yuki wurde auf Izumi korrigiert (vorher fälschlich +Benjiro). Bitte Stammbaum neu laden." — keine Code-/Fachbegriffe. + +## Verifikation vor „fertig" +- Code-Fixes: `npx tsc --noEmit`, `npx vitest run`, betroffene `npx playwright test`, + `dotnet build`/`dotnet test`, Python-`test_*.py` — grün. +- Daten-Fixes: in `resolved_import.json` stichprobenartig prüfen, dann re-ingest + + API-Check des konkreten Tiers/Wurfs. +- Jedes erledigte Ticket auf `Resolved` mit `fixNote` gesetzt. + +## Hinweise +- Pro Ticket genau ein Triage-Agent; Umsetzung gebündelt nach Cluster. +- Encoding: deutsche Texte als UTF-8 (Datei, nicht stdin-Pipe). +- Nichts committen, bis der Haupt-Loop verifiziert hat; auf `main` arbeiten.