---
name: gh-tickets
description: "Konventionen für GitHub-Issues in diesem Workspace: Aufgabentyp-Labels, Sortierung über das Project Board (Number-Feld 'Order') und CLI-Abfragen. Verwende diesen Skill immer dann, wenn Issues angelegt, abgefragt, sortiert oder vom nextstep-Router verarbeitet werden. Trigger-Phrasen: 'nächstes Ticket', 'Issue anlegen', 'Reihenfolge', 'Priorität', 'nextstep', 'Order', 'Board'."
---

# Skill: GitHub Tickets (gh-tickets)

Dieses Dokument definiert die verbindlichen Konventionen für GitHub-Issues im Repository `jreinemann-euris/bollwerk`.

---

## 1. Aufgabentyp (Pflicht-Label)

Jedes Issue MUSS genau **eines** dieser Type-Labels tragen:

| Label            | Kürzel | Beschreibung                                                                   |
| ---------------- | ------ | ------------------------------------------------------------------------------ |
| `block-planning` | [B]    | Grobplanung – zerlegt Projekt in Blocks, erstellt [T]- und [P]-Tickets         |
| `feature`        | [F]    | Feature-Entwicklung – Neuentwicklung ohne Referenz-Altcode                     |
| `refactoring`    | [F]    | Architektur-Refactoring – wird wie Feature behandelt (workflow-implementation) |
| `tech-decision`  | [T]    | Technologie-Entscheidung (User trifft die Wahl)                                |
| `infrastructure` | [I]    | Infrastruktur, Prozess, Tooling, Dokumentation                                 |
| `planning`       | [P]    | Planungsaufgabe – zerlegt grobes Ticket in Arbeitspakete                       |
| `test`           | [X]    | Generaltest oder Coverage-Check eines abgeschlossenen Bereichs                 |

### Validierung

Bevor ein Workflow gestartet wird, prüfe ob das Issue ein Type-Label hat. Falls nicht:

```
⚠️  Issue #<N> hat kein Type-Label (block-planning/feature/migration/refactoring/tech-decision/infrastructure/planning/test).
    Bitte eines der Labels zuweisen, bevor der Workflow starten kann.
```

Stoppe und fordere den User zur Zuordnung auf. Starte den Workflow **nicht** ohne Type-Label.

### Mapping zum Workflow

| Label            | Workflow-Prompt                                     |
| ---------------- | --------------------------------------------------- |
| `block-planning` | `.github/prompts/nextstep-block-planning.prompt.md` |
| `feature`        | `.github/prompts/nextstep-implementation.prompt.md` |
| `migration`      | `.github/prompts/nextstep-implementation.prompt.md` |
| `refactoring`    | `.github/prompts/nextstep-implementation.prompt.md` |
| `tech-decision`  | `.github/prompts/nextstep-tech-decision.prompt.md`  |
| `infrastructure` | `.github/prompts/nextstep-infrastructure.prompt.md` |
| `planning`       | `.github/prompts/nextstep-planning.prompt.md`       |
| `test`           | `.github/prompts/nextstep-test.prompt.md`           |

---

## 2. Sortierung über Project Board

Die Abarbeitungsreihenfolge wird über das **Project Board** gesteuert, nicht über Labels.

### Board-Daten

| Eigenschaft  | Wert                                                 |
| ------------ | ---------------------------------------------------- |
| Projekt-Name | `Bollwerk`                                           |
| Projekt-Nr   | `2`                                                  |
| Owner        | `jreinemann-euris`                                   |
| Sortierfeld  | `Order` (Number-Feld)                                |
| URL          | https://github.com/users/jreinemann-euris/projects/2 |

### Order-Feld Konventionen

- **Kleinere Zahl = höhere Priorität** (wird zuerst abgearbeitet)
- **Jeder Order-Wert MUSS eindeutig sein** – keine zwei Items dürfen denselben Wert haben
- Standardwerte: 10, 20, 30, 40, … (in 10er-Schritten, um Platz für Einfügungen zu lassen)
- Ein dringend vorgezogenes Ticket bekommt einen Wert **zwischen** den bestehenden (z.B. 15 zwischen 10 und 20, oder 5 vor 10)
- Wenn keine bestimmte Position vorgegeben ist, erhält das Ticket den **höchsten bestehenden Order-Wert + 10** (= wird am Ende eingefügt)
- Items ohne Order-Wert sind ein **Fehler** und müssen sofort einen Order-Wert erhalten

### Nächstes offenes Issue ermitteln

**Skript:** `.github/skills/gh-tickets/next-ticket.ps1`

```powershell
# Nächstes Ticket (priority:high zuerst, dann Order aufsteigend):
& ".github/skills/gh-tickets/next-ticket.ps1"

# Bestimmtes Issue abfragen (Typ-Label prüfen):
& ".github/skills/gh-tickets/next-ticket.ps1" -IssueNumber 98
```

Ausgabe: `#68 [M] CRM: Erweiterte Kundensuche (Order: 120)`

### Issue zum Board hinzufügen

```powershell
# Issue zum Board hinzufügen
gh project item-add 2 --owner jreinemann-euris --url "https://github.com/jreinemann-euris/bollwerk/issues/<N>"

# Order-Wert setzen (erfordert Item-ID und Field-ID)
gh project item-edit --id <ITEM_ID> --field-id <ORDER_FIELD_ID> --project-id <PROJECT_ID> --number <ORDER_VALUE>
```

### Board-Status aktualisieren

**Skript:** `.github/skills/gh-tickets/set-board-status.ps1`

```powershell
# Status auf "In Progress" setzen
& ".github/skills/gh-tickets/set-board-status.ps1" -IssueNumber 68 -Status InProgress

# Status auf "Done" setzen
& ".github/skills/gh-tickets/set-board-status.ps1" -IssueNumber 68 -Status Done

# Status auf "Todo" zurücksetzen
& ".github/skills/gh-tickets/set-board-status.ps1" -IssueNumber 68 -Status Todo
```

Gültige Status-Werte: `Todo`, `InProgress`, `Done`

---

## 3. Issue anlegen (Checkliste)

Beim Anlegen eines neuen Issues **MÜSSEN alle 5 Schritte** durchgeführt werden:

1. **Titel**: Beschreibend, ggf. mit Modulpräfix (z.B. `CRM:`, `feat(core):`)
2. **Type-Label**: Genau eines von `migration`, `tech-decision`, `infrastructure`, `planning`, `test`
3. **Weitere Labels**: Optional (z.B. `crm`, `enhancement`)
4. **Board**: Issue **sofort** zum Project Board hinzufügen (ein Issue ohne Board-Eintrag existiert nicht für die Abarbeitung!)
5. **Order**: **Eindeutigen** Order-Wert setzen. Vor dem Setzen die bestehenden Order-Werte abfragen und sicherstellen, dass der gewählte Wert noch nicht vergeben ist. Ohne spezifische Positionsvorgabe: höchsten bestehenden Wert + 10

> **Kein Issue ohne Board + Order!** Ein Issue ohne Board-Eintrag wird bei „nächste Aufgabe" nicht gefunden.

### Dringend vorgezogenes Issue anlegen ("als nächstes")

**Skript:** `.github/skills/gh-tickets/create-next-ticket.ps1`

Wenn während einer laufenden Aufgabe ein neues Issue entdeckt wird, das **direkt danach** bearbeitet werden soll:

```powershell
# Issue anlegen und als nächstes Ticket einsortieren (niedrigster Order-Wert)
& ".github/skills/gh-tickets/create-next-ticket.ps1" -Title "CRM: Bug in Kundensuche" -Labels "migration,crm" -Body "Beschreibung..."
```

Das Skript erledigt automatisch alle 5 Schritte: Issue anlegen, Board hinzufügen, Order auf niedrigsten Wert setzen.
**Trigger-Phrasen:** „als nächstes anlegen", „nächstes Ticket erstellen", „direkt danach bearbeiten"

---

## 4. Sortierung: Priorität + Order (zweistufig)

Die Abarbeitungsreihenfolge wird **zweistufig** bestimmt:

1. **Primär: Label `priority:high`** → Issues mit diesem Label kommen **immer zuerst**, unabhängig vom Order-Wert
2. **Sekundär: Label `priority:low`** → Issues mit diesem Label kommen **immer zuletzt**, unabhängig vom Order-Wert
3. **Tertiär: Order-Feld** → Innerhalb derselben Prioritätsstufe sortiert der Order-Wert aufsteigend (kleinere Zahl = früher dran)

Beispiel: Ein Issue mit `priority:high` und Order 300 kommt **vor** einem Issue ohne Priorität mit Order 5. Ein normales Issue mit Order 999 kommt **vor** einem `priority:low`-Issue mit Order 1.
