pi_coder_2/BEDIENUNGSANLEITUNG.md

# Bedienungsanleitung: pi_coder

pi_coder ist ein Werkzeug, das ein lokales KI-Modell abwechselnd als **Coder** und **Judge**
einsetzt, um Software automatisch zu schreiben, zu prüfen und zu verbessern — alles gesteuert
über einfache Slash-Kommandos in der pi-Agent-Oberfläche.

---

## Inhaltsverzeichnis

1. [Konzept: Coder und Judge](#1-konzept-coder-und-judge)
2. [Vorbereitung](#2-vorbereitung)
3. [Server starten und stoppen](#3-server-starten-und-stoppen)
4. [Neues Projekt anlegen](#4-neues-projekt-anlegen)
5. [Manueller Workflow: /coder → /judge → /fix → /shipit](#5-manueller-workflow)
6. [Automatischer Workflow: /optimize](#6-automatischer-workflow-optimize) (inkl. [Interactive-Modus](#interactive-modus))
7. [Kleine Änderungen: /patch und /quick_check](#7-kleine-änderungen-patch-und-quick_check)
8. [Dokumentation generieren: /update_doku](#8-dokumentation-generieren-update_doku)
9. [Versionsverwaltung: /version](#9-versionsverwaltung-version)
10. [TASK.md verstehen und nutzen](#10-taskmd-verstehen-und-nutzen)
11. [Typische Anwendungsfälle](#11-typische-anwendungsfälle)
12. [Fehlermeldungen und Lösungen](#12-fehlermeldungen-und-lösungen)

---

## 1. Konzept: Coder und Judge

pi_coder verwendet zwei Rollen — bedient von **einem einzigen Modell**, das je nach Aufgabe
eine andere Persona annimmt:

**Coder-Persona**: Schreibt und repariert Code. Liest die Aufgabe aus `TASK.md`, implementiert
sie, führt Tests aus und erstellt Git-Commits.

**Judge-Persona**: Überprüft den Code mit dem Blick eines skeptischen Senior-Entwicklers.
Prüft Korrektheit, Robustheit, Randfälle, Sicherheit und Produktionsreife. Gibt ein Urteil:
- `PASS` — Code ist in Ordnung
- `PASS WITH CONCERNS` — hat Anmerkungen, die behoben werden müssen (wird wie `FAIL` behandelt,
  außer du verwendest `--approve-concerns`)
- `FAIL` — enthält Blocker, die behoben werden müssen

Die Umschaltung zwischen den Rollen erfolgt über unterschiedliche System-Prompts, die die
Extension automatisch vor jeder Inference einsetzt. Es läuft kein zweiter Server.

Der Grundgedanke: Coder und Judge haben keine „Höflichkeitsschranke" zueinander —
der Judge kritisiert direkt und konkret, der Coder repariert ohne Widerspruch.

---

## 2. Vorbereitung

### Server starten

```bash
cd ~/pi_coder
./start-coding-server.sh
```

Ausgabe bei Erfolg:
```
[*] Verwende HF_HOME = /home/.../huggingface
[*] GPU device = 1
[✓] Single-Server (:8001) bereit
```

Dauer: bis zu 5 Minuten (Modell wird in GPU-VRAM geladen; neuere llama.cpp-Versionen
prüfen beim Start die VRAM-Verfügbarkeit, was zusätzliche Zeit kostet).

### Status prüfen

```bash
./status-coding-server.sh
```

```
=== LLaMA-Server Status ===
coding_model (Port 8001): Container=RUNNING  HTTP=OK
```

### pi agent öffnen

pi agent im Projektverzeichnis starten — das ist das Verzeichnis, in dem dein Code liegt,
**nicht** `~/pi_coder`:

```bash
cd ~/MeinProjekt
pi
```

---

## 3. Server starten und stoppen

### GPU-Zuordnung

Der Server läuft standardmäßig auf **GPU 1** (überschreibbar):

```bash
./start-coding-server.sh           # GPU 1 (Standard)
GPU_DEVICE=0 ./start-coding-server.sh   # GPU 0
```

Auf einem System mit mehreren GPUs empfiehlt es sich, GPU 0 (Display) freizuhalten
und GPU 1 für den KI-Server zu verwenden.

**Wichtig:** Andere GPU-Prozesse (z. B. TTS-Dienste, Ollama) auf der verwendeten GPU
können VRAM belegen und dazu führen, dass der Server nicht startet. Im Zweifel prüfen:
```bash
nvidia-smi --query-gpu=index,name,memory.used,memory.free --format=csv
```

### Server starten

```bash
cd ~/pi_coder
./start-coding-server.sh
```

Erwartete Ausgabe:
```
[*] Verwende HF_HOME = /home/.../huggingface
[*] GPU device = 1
[✓] Single-Server (:8001) bereit
```

Dauer: bis zu 5 Minuten. Danach ist das Modell im VRAM und sofort antwortbereit.

### Server stoppen

```bash
./stop-coding-server.sh
```

### Status prüfen

```bash
./status-coding-server.sh
```

### Alternativer Modellpfad

Falls die GGUF-Datei an einem anderen Ort liegt:

```bash
HF_HOME=/mnt/daten/huggingface ./start-coding-server.sh
```

---

## 4. Neues Projekt anlegen

### Kommando

```
/new_project <pfad>
```

### Beispiel

```
/new_project ~/Python_Programs/mein_tool
```

Was passiert:
- Verzeichnis `~/Python_Programs/mein_tool` wird angelegt
- `git init` wird ausgeführt
- `.gitignore` wird mit Standardeinträgen angelegt und committed

**Wichtig:** pi agent wechselt **nicht automatisch** in das neue Verzeichnis —
die Session bleibt im aktuellen Verzeichnis. Nach dem Anlegen:

```bash
cd ~/Python_Programs/mein_tool
pi
```

Dann kannst du `/coder` oder `/optimize` mit dem neuen Projekt verwenden.

---

## 5. Manueller Workflow

Der manuelle Workflow gibt dir volle Kontrolle über jeden Schritt.

### Schritt 1: /coder — Aufgabe übergeben

```
/coder <auftrag>
```

Der Coder:
1. Legt `TASK.md` im aktuellen Verzeichnis an (oder hängt an bestehende an)
2. Liest `TASK.md` und implementiert den Auftrag
3. Führt Tests oder Build-Checks aus
4. Erstellt einen Git-Commit

**Beispiel:**

```
/coder Schreibe ein Python-Kommandozeilenprogramm 'textcount'. Es soll eine Textdatei als Argument nehmen und folgendes ausgeben: Anzahl Zeichen, Wörter, Zeilen und die 5 häufigsten Wörter (ohne Stoppwörter).
```

Typische Ausgabe des Coders:
```
Implementierung abgeschlossen.
- src/textcount.py erstellt (Hauptprogramm)
- tests/test_textcount.py erstellt (Unit-Tests)
- requirements.txt angelegt (keine externen Abhängigkeiten)
- Alle 8 Tests bestanden
- Commit: feat: implement textcount CLI tool
Risiken: Stoppwortliste nur Deutsch/Englisch, keine Konfigurations-Option.
```

### Schritt 2: /judge — Code überprüfen lassen

```
/judge
```

Optionaler Fokus:
```
/judge Besonderes Augenmerk auf Fehlerbehandlung und Edge Cases
```

Der Judge:
1. Liest `TASK.md` und prüft ob alle Anforderungen umgesetzt sind
2. Analysiert `git show HEAD`
3. Führt Tests aus
4. Gibt ein strukturiertes Urteil aus

**Beispiel-Ausgabe PASS WITH CONCERNS:**
```
Urteil: PASS WITH CONCERNS

Blocker: keine

Major:
- Stoppwortliste ist hardcoded; große Projekte erwarten --stopwords-file Option

Minor:
- Keine --version Flag
- Fehlermeldung bei nicht-existenter Datei gibt keinen Exit-Code 1 zurück

Fehlende Tests:
- Test für leere Datei fehlt
- Test für Datei mit nur Leerzeichen fehlt

Produktionsrisiken:
- Bei sehr großen Dateien (>1 GB) wird alles in den RAM geladen

Konkrete Fix-Aufträge:
1. exit(1) bei FileNotFoundError
2. Test für leere Eingabedatei
```

**Beispiel-Ausgabe FAIL:**
```
Urteil: FAIL

Blocker:
- textcount.py importiert 'collections.Counter' aber das ist nicht installiert
  (Counter ist stdlib, aber der Import-Fehler tritt bei Python < 3.9 auf)
- ./textcount.py existiert nicht — tests/test_textcount.py schlägt komplett fehl

Major: ...
```

### Schritt 3: /fix — Kritik beheben

```
/fix
```

Optionaler Hinweis:
```
/fix Den Major-Punkt mit der Stoppwortliste kannst du weglassen, das ist kein Produktionsprojekt
```

Der Coder arbeitet die Judge-Kritik ab (Blocker zuerst, dann Major, dann Minor)
und erstellt einen neuen Commit.

### Schritt 4: /shipit — Finale Freigabe

```
/shipit
```

Der Judge gibt ein finales Urteil:
- `SHIP` — bereit für Produktion
- `NO-SHIP` — noch Probleme offen

**Beispiel:**
```
Urteil: SHIP

Letzte Blocker: keine

Restrisiken:
- Kein Streaming für sehr große Dateien (dokumentiert in README)

Empfohlene Sofortmaßnahmen: keine
```

---

## 6. Automatischer Workflow: /optimize

`/optimize` führt den gesamten Coder→Judge→Fix-Zyklus automatisch durch.

### Syntax

```
/optimize <auftrag> [--rounds N] [--with-doku] [--continue] [--interactive]
          [--no-tests] [--approve-concerns] [--test-cmd "cmd"] [--test-timeout N]
```

- `--rounds N` — maximale Anzahl Runden (Standard: 2)
- `--with-doku` — nach SHIP automatisch `/update_doku` ausführen
- `--continue` — überspringt die Implementierungsphase und startet direkt mit dem
  Judge→Fix-Zyklus ab dem aktuellen Code-Stand. Nützlich wenn man bereits manuell
  `/coder`, `/judge` und `/fix` durchgeführt hat und den Rest automatisieren möchte.
- `--interactive` — pausiert nach erstem PASS für einen menschlichen Checkpoint.
  Details: siehe [Interactive-Modus](#interactive-modus) weiter unten.
- `--no-tests` — überspringt die automatische Test-Erkennung. Sinnvoll wenn keine
  Test-Suite vorhanden ist oder Tests über externe Infrastruktur laufen.
- `--approve-concerns` — behandelt „PASS WITH CONCERNS" wie „PASS": kein ShipIt-Call,
  direktes SHIP. Standardmäßig löst PASS WITH CONCERNS immer einen Coder-Fix aus.
- `--test-cmd "befehl"` — überschreibt die automatische Test-Erkennung mit einem
  eigenen Befehl (z.B. `--test-cmd "pytest tests/ -x"`).
- `--test-timeout N` — maximale Laufzeit pro Test-Befehl in Sekunden (Standard: 120).

### PASS WITH CONCERNS — wichtig

Ohne `--approve-concerns` gilt `PASS WITH CONCERNS` **wie `FAIL`** — der Coder bekommt
einen Fix-Auftrag und der Loop geht weiter. Erst sauberes `PASS` beendet die Schleife.
Mit `--approve-concerns` gilt PASS WITH CONCERNS als bestanden.

### Beispiel: einfacher Auftrag

```
/optimize Schreibe ein Rust-Programm 'genpw' das sichere Passwörter generiert. Optionen: --length N (Standard 16), --count N (Standard 1), --no-symbols, --no-numbers.
```

Was im Hintergrund passiert:
```
Phase 1: Coder implementiert...
Phase 2: Runde 1/2: Judge — TASK.md + letzter Commit + Tests...
  → Urteil: FAIL (2 Blocker)
Phase 3: Runde 1/2: Coder fixt...
Phase 4: Runde 2/2: Judge — TASK.md + letzter Commit + Tests...
  → Urteil: PASS
✓ PASS nach Runde 2 → SHIP
[Dialog: Version → v0.1.0 (empfohlen)]
```

Bei `PASS WITH CONCERNS` (ohne --approve-concerns):
```
  → Urteil: PASS WITH CONCERNS (Major: fehlendes --help)
Phase 3: Runde 2/2: Coder fixt Concerns...
Phase 4: Runde 3/3: Judge...
  → Urteil: PASS
✓ PASS → SHIP
```

Bei klarem `PASS` entfällt die ShipIt-Runde — es wird direkt SHIP ausgelöst.

Während des Ablaufs zeigt die Statuszeile die aktuelle Phase — mit laufendem Timer:

```
◉ Coder implementiert: Login-Flow mit JWT [01:23]
◉○ Runde 1/2: Judge — TASK.md + letzter Commit + Tests [00:47]
●◉ Runde 1/2: Coder fixt — fehlendes Null-Check [01:05]
●● ✓ PASS nach Runde 2/2 — SHIP
🚀 SHIP – produktionsreif
```

Steht der Timer still, hängt der Prozess — dann `/cancel` verwenden.

### Beispiel: mehr Runden

```
/optimize Implementiere einen vollständigen REST-API-Client für die GitHub API in Python mit Rate-Limiting, Retry-Logic und Caching --rounds 5
```

### Beispiel: mit automatischer Dokumentation

```
/optimize Schreibe ein Go-Tool 'logfilter' das Logdateien nach Regex-Muster filtert --with-doku
```

Nach SHIP werden automatisch ausgeführt:
1. Code-Kommentare einfügen
2. README.md schreiben
3. BEDIENUNGSANLEITUNG.md schreiben
4. LICENCE.md anlegen (falls noch nicht vorhanden)

### Vom manuellen Workflow in den automatischen wechseln

Du hast bereits `/coder`, `/judge` und `/fix` manuell durchgeführt und möchtest
den Rest automatisch ablaufen lassen:

```
/optimize --continue
```

```
/optimize --continue --rounds 5
```

```
/optimize --continue --with-doku
```

Die Implementierungsphase wird übersprungen — der Judge prüft sofort den aktuellen
Stand und der Fix-Zyklus läuft automatisch bis PASS oder max. N Runden.

### Loop-Erkennung

Wenn zweimal hintereinander genau dieselben Blocker oder Concerns auftreten, bricht
`/optimize` ab:
```
⚠ Derselbe Blocker tritt erneut auf – Schleife abgebrochen. Bitte manuell prüfen.
```

In diesem Fall: `/judge` manuell ausführen, Blocker lesen, mit `/fix` manuell eingreifen.

### Max. Runden ohne PASS

```
⚠ 2 Runden durchlaufen ohne PASS. Bitte manuell prüfen.
```

Dann: `/judge` und `/fix` manuell für gezielte Eingriffe.
Mit `--rounds N` kann die Grenze hochgesetzt werden, z.B. `--rounds 5` für komplexe Aufgaben.

### Interactive-Modus

Mit `--interactive` pausiert `/optimize` nach dem ersten PASS und wartet auf menschliches
Feedback — bevor das abschließende SHIP ausgelöst wird.

```
/optimize Implementiere Feature X --interactive
```

Typischer Ablauf:
```
Phase 1: Coder implementiert...
Phase 2: Judge prüft...
  → Urteil: PASS
⏸ PASS erreicht. Weitere Features? /continue "Zusatzauftrag" — oder /continue zum Shippern.
```

Jetzt hast du drei Optionen:

**Option A: Direkt shippern**
```
/continue
```
→ ShipIt wird gestartet, Version-Dialog erscheint.

**Option B: Zusatzauftrag hinzufügen**
```
/continue "Füge außerdem eine --verbose Option hinzu"
```
→ Coder implementiert den Zusatz, dann läuft der Judge-Loop erneut an.
→ Nach erneutem PASS erscheint der Checkpoint wieder — du kannst beliebig viele
  Iterationen anhängen, bevor du mit `/continue` zum SHIP gehst.

**Option C: Abbrechen**
```
/cancel
```
→ Loop wird abgebrochen, kein SHIP.

**Timeout:** Wenn du 30 Minuten lang nichts eingibst, bricht `/optimize` automatisch ab.

**Wann ist `--interactive` sinnvoll?**
- Wenn der Auftrag aus mehreren voneinander abhängigen Features besteht
- Wenn du nach jeder fertigen Stufe entscheiden möchtest, ob du weitermachst
- Wenn du sicherstellen willst, dass nichts unbeabsichtigt committed wird

---

## 7. Kleine Änderungen: /patch und /quick_check

Für minimale Korrekturen — kein voller Review-Zyklus, keine TASK.md-Änderungen.

### /patch — kleine Änderung umsetzen

```
/patch <beschreibung der änderung>
```

Der Coder ändert **ausschließlich** das Beschriebene, prüft ob es noch kompiliert/startet
und erstellt einen Commit.

**Beispiele:**

```
/patch Mindestpasswortlänge von 4 auf 8 Zeichen erhöhen
```

```
/patch Fehlermeldung bei ungültigem Argument von stderr auf stdout umleiten
```

```
/patch Versionsnummer in Cargo.toml von 0.1.0 auf 0.2.0 erhöhen
```

```
/patch Die Funktion parse_args() soll bei fehlendem --input-Argument eine sinnvolle Hilfsnachricht ausgeben statt zu paniken
```

### /quick_check — Änderung schnell prüfen lassen

```
/quick_check [was geprüft werden soll]
```

Der Judge schaut sich `git show HEAD` an und gibt nur `OK` oder `PROBLEM` zurück.

**Beispiele:**

```
/quick_check
```

```
/quick_check Prüfe ob die Mindestlängen-Änderung korrekt umgesetzt ist und keine Randfälle fehlen
```

**Typische Ausgaben:**

```
Urteil: OK

Die Änderung in src/main.rs Zeile 47 ist korrekt. Mindestlänge wird jetzt
sowohl bei --length als auch im Standardfall geprüft.
```

```
Urteil: PROBLEM

src/lib.rs Zeile 23: Der neue Mindestwert von 8 wird nur bei --length geprüft,
nicht beim Standardwert (16). Wenn jemand --length 6 übergibt, schlägt die
Validierung korrekt fehl, aber der Standardfall ist nicht abgedeckt.
Fix: Validierung in die Funktion generate_password() verschieben statt in parse_args().
```

### Typischer /patch + /quick_check Workflow

```
/patch Timeout bei HTTP-Requests von 30 auf 10 Sekunden setzen
```
*(Coder ändert, committet)*

```
/quick_check Prüfe ob der Timeout auch bei Retry-Versuchen korrekt gilt
```
*(Judge gibt OK oder zeigt konkretes Problem)*

---

## 8. Dokumentation generieren: /update_doku

Nach Abschluss der Entwicklung (nach `/shipit` oder `/optimize`) erstellt `/update_doku`
vier Dinge automatisch:

1. **Code-Kommentare** — erklärt das WARUM in den Quelldateien (Deutsch)
2. **README.md** — Entwicklerperspektive: Installation, Build, Verwendung
3. **BEDIENUNGSANLEITUNG.md** — Endnutzerperspektive: einfach, ohne Jargon
4. **LICENCE.md** — proprietäre Lizenz mit aktuellem Jahr und Inhaber aus `git config user.name`
   (wird nur angelegt wenn noch keine `LICENCE.md` vorhanden ist — existierende Lizenzen
   werden nie überschrieben)

```
/update_doku
```

### Inkrementelles Update

`/update_doku` merkt sich via Git-Tags welche Dateien seit dem letzten Lauf geändert wurden.
Nur geänderte Quelldateien werden neu kommentiert — unveränderte bleiben unangetastet.

```
Code-Kommentare: keine Änderungen seit letztem Lauf – übersprungen.
README.md: 2 Datei(en) geändert – wird geprüft
BEDIENUNGSANLEITUNG.md: 2 Datei(en) geändert – wird geprüft
LICENCE.md: bereits vorhanden – übersprungen.
```

### Zusammen mit /optimize

```
/optimize Implementiere Feature X --with-doku
```

Führt nach SHIP automatisch `/update_doku` aus.

---

## 9. Versionsverwaltung: /version

pi_coder verwaltet Versionsnummern im SemVer-Format (`vMAJOR.MINOR.PATCH`) automatisch —
basierend auf den Commit-Messages des generierten Codes.

### Wie Commit-Messages die Version bestimmen

Der Coder verwendet standardmäßig das Conventional-Commits-Format:

| Commit-Prefix | Beispiel | Bump-Typ |
|---|---|---|
| `feat!:` oder `BREAKING CHANGE` | `feat!: API komplett überarbeitet` | major (v1.0.0 → v2.0.0) |
| `feat:` | `feat: CSV-Export hinzugefügt` | minor (v1.0.0 → v1.1.0) |
| `fix:`, `chore:`, andere | `fix: Crash bei leerer Datei` | patch (v1.0.0 → v1.0.1) |

### Automatisch nach SHIP

Nach einem erfolgreichen SHIP-Verdikt in `/optimize` oder `/shipit` erscheint automatisch
ein Dialog:

```
┌─ Version ──────────────────────────────────────────────┐
│ Aktuelle Version: v1.2.3. Commits seit letztem Tag:    │
│ minor-Bump erkannt.                                     │
│                                                         │
│  patch → v1.2.4                                         │
│  minor → v1.3.0  (empfohlen)                           │
│  major → v2.0.0                                         │
│  Überspringen                                           │
└─────────────────────────────────────────────────────────┘
```

Du kannst den empfohlenen Wert bestätigen oder manuell einen anderen wählen.

### Manuell aufrufen

```
/version
```

Nützlich wenn du den Tag nachträglich setzen möchtest oder nach manuellen Commits.

### Was passiert nach der Auswahl

1. Die Versionsnummer wird in die Projekt-Manifest-Datei geschrieben (falls vorhanden):
   - `package.json` → `npm version --no-git-tag-version X.Y.Z`
   - `Cargo.toml` → `version = "X.Y.Z"` in `[package]`
   - `pyproject.toml` → `version = "X.Y.Z"` in `[project]`
   - `VERSION` → Dateiinhalt `vX.Y.Z`
2. Commit: `chore: bump version to vX.Y.Z`
3. Git-Tag: `vX.Y.Z` wird gesetzt

Wenn keine der genannten Dateien vorhanden ist, wird nur der Git-Tag gesetzt.

### Erstes Mal — kein Tag vorhanden

```
┌─ Version ──────────────────────────────────────────────┐
│ Noch kein Versions-Tag vorhanden.                       │
│                                                         │
│  patch → v0.0.1                                         │
│  minor → v0.1.0  (empfohlen)                           │
│  major → v1.0.0                                         │
│  Überspringen                                           │
└─────────────────────────────────────────────────────────┘
```

Empfehlung: `v0.1.0` für ein frisches, funktionierendes Projekt; `v1.0.0` wenn es
sofort produktionsreif ist.

---

## 10. TASK.md verstehen und nutzen

`TASK.md` ist die persistente Aufgabenbeschreibung im Projektverzeichnis. Sie wird von
allen Kommandos als Referenz gelesen.

### Erstellt von /coder und /optimize

Beim ersten `/coder`-Aufruf:
```markdown
# Aufgabe

Schreibe ein Python-Kommandozeilenprogramm 'textcount'...

## Erstellt
2026-05-19T14:30:00.000Z

## Status
- [ ] Implementierung
- [x] Review bestanden (PASS)
- [ ] Produktionsreif (SHIP)
```

### Zusatzauftrag hinzufügen

Wenn du später `/coder` mit einer neuen Aufgabe aufrufst, wird TASK.md erweitert statt überschrieben:

```
/coder Füge zusätzlich eine --csv-Option hinzu, die das Ergebnis als CSV ausgibt
```

```markdown
# Aufgabe

[...ursprüngliche Aufgabe...]

---

## Zusatzauftrag

2026-05-19T15:45:00.000Z

Füge zusätzlich eine --csv-Option hinzu...

## Status
- [ ] Implementierung
- [ ] Review bestanden (PASS)
- [ ] Produktionsreif (SHIP)
```

### Status-Checkboxen

Die Checkboxen werden automatisch abgehakt:
- `[x] Implementierung` — nach erfolgreichem `/coder` oder `Phase 1` von `/optimize`
- `[x] Review bestanden (PASS)` — nach PASS durch `/judge` oder in `/optimize`
- `[x] Produktionsreif (SHIP)` — nach SHIP durch `/shipit` oder `/update_doku`

---

## 11. Typische Anwendungsfälle

### Neues Rust-Programm von Null

```bash
# 1. Verzeichnis anlegen
/new_project ~/Rust_Programs/mein_tool

# 2. Terminal: in Verzeichnis wechseln und pi neu starten
# cd ~/Rust_Programs/mein_tool && pi

# 3. In pi: vollautomatisch implementieren + dokumentieren
/optimize Schreibe ein Rust-CLI-Tool 'csvfilter' das CSV-Dateien zeilenweise filtert. Optionen: --column NAME, --value WERT, --regex. Ausgabe auf stdout. --with-doku
```

### Bestehendes Projekt verbessern

```bash
# In pi, im Projektverzeichnis:
/coder Refaktoriere die Datenbankschicht: ersetze das raw-SQL durch sqlx mit typsicheren Queries. Alle Tests müssen danach noch laufen.
/judge
/fix
/shipit
```

### Schnelle Bugfixes

```bash
/patch Die Funktion split_csv() schlägt bei Feldern mit eingebetteten Kommas fehl (RFC 4180 nicht implementiert)
/quick_check
```

### Repo ohne Test-Suite oder mit externer CI

```bash
# Test-Erkennung überspringen — Judge bewertet nur den Code
/optimize "Implementiere Feature X" --no-tests

# Externe Test-Suite explizit angeben
/optimize "Implementiere Feature X" --test-cmd "make integration-test"
```

### Schneller Loop ohne ShipIt-Runde

```bash
# Für Projekte wo "PASS WITH CONCERNS" ausreicht:
/optimize "Kleines Refactoring" --approve-concerns

# Kombination: kein Test, PASS WITH CONCERNS akzeptieren, 1 Runde
/optimize "Typo-Fix in Fehlermeldungen" --rounds 1 --no-tests --approve-concerns
```

### Versionsnummer nach der Entwicklung setzen

```bash
# Nach SHIP: Dialog erscheint automatisch
/optimize Neues Feature X --rounds 2
# → SHIP → Dialog → "minor → v1.1.0" wählen → Tag gesetzt

# Oder manuell:
/version
```

### Kommentarlosen Legacy-Code dokumentieren

```bash
# Nur Kommentare und Dokumentation, kein Code ändern:
/update_doku
```

### Schrittweise mit manuellem Review

```bash
/coder Implementiere OAuth2-Login mit GitHub
# → Code lesen, verstehen
/judge Besonderes Augenmerk auf Token-Speicherung und CSRF-Schutz
# → Judge-Bericht lesen
/fix Ignoriere den Minor-Punkt mit der Logging-Verbosität, das ist Absicht
/shipit
```

### Experiment: mehrere Runden explizit

```bash
/optimize Schreibe einen vollständigen Markdown-Parser mit AST in Python --rounds 5
```

### Schrittweise Features hinzufügen mit --interactive

```bash
# Erst Grundgerüst implementieren und PASS abwarten:
/optimize Schreibe ein CLI-Tool 'filewatch' das Dateiänderungen überwacht --interactive

# Nach PASS erscheint: ⏸ PASS – warte auf /continue…

# Option A: Genug, direkt shippern:
/continue

# Option B: Weiteres Feature anhängen:
/continue "Füge außerdem einen --filter GLOB-Parameter hinzu"
# → Coder implementiert, Judge prüft erneut, PASS → Checkpoint wieder aktiv

# Nochmal erweitern:
/continue "Füge --output-log DATEI hinzu um Änderungen zu protokollieren"

# Fertig → shippern:
/continue
```

---

## 12. Fehlermeldungen und Lösungen

### "Modell-Datei nicht gefunden"

```
[!] Modell-Datei nicht gefunden: /home/.../models/qwen3/Qwen3.6-27B-Uncensored-...gguf
```

**Ursache:** Die GGUF-Datei liegt nicht am erwarteten Ort.

**Lösung:**
```bash
# Pfad prüfen:
ls $HF_HOME/models/qwen3/

# Oder mit explizitem Pfad starten:
HF_HOME=/korrekter/pfad ./start-coding-server.sh
```

### Server startet nicht / HTTP nicht erreichbar

```
[!] HTTP-Server wurde nicht rechtzeitig erreichbar.
```

**Ursachen und Lösungen:**

1. Zu wenig VRAM — Container bricht beim Laden ab:
   ```bash
   docker logs coding_model | tail -50
   # Suche nach: "CUDA out of memory" oder "failed to allocate"
   ```
   → Kontext reduzieren: `-c 65536` statt `-c 262144` in `start-coding-server.sh`

2. GPU nicht verfügbar:
   ```bash
   nvidia-smi   # GPU sichtbar?
   # GPU 1 testen:
   docker run --gpus '"device=1"' --rm nvidia/cuda:12.0-base nvidia-smi
   # Andere GPU testen:
   GPU_DEVICE=0 ./start-coding-server.sh
   ```

3. Port 8001 bereits belegt:
   ```bash
   ss -tlnp | grep 8001
   docker ps -a   # alter Container noch vorhanden?
   ./stop-coding-server.sh
   ./start-coding-server.sh
   ```

### "Agent is already processing a prompt"

**Ursache:** Ein Kommando wurde aufgerufen während pi agent noch auf eine Antwort wartet.

**Lösung:** Warten bis die aktuelle Antwort fertig ist, dann das Kommando wiederholen.
Bei `/optimize` passiert das automatisch — der interne Mechanismus wartet auf `idle`.

### "edits[n] ... oldText must match exactly"

**Ursache:** Der interne pi-agent-Edit-Mechanismus hat beim Anwenden mehrerer Änderungen
an derselben Datei versagt.

**Was pi_coder dagegen tut:** Ein `tool_call`-Hook in der Extension sortiert
Mehrfach-Edits automatisch von hinten nach vorne (Bottom-up-Reordering), sodass
frühere Edits spätere Positionen nicht verschieben. Zusätzlich steht das `apply_patch`-Tool
bereit, das GNU `patch -p1` mit Fuzzy-Matching nutzt.

**Falls es trotzdem auftritt:** Das Modell manuell anweisen:
```
Lies die Datei neu ein und wende die Änderungen als unified diff mit apply_patch an.
```

### "N Runden ohne PASS" / Loop-Erkennung schlägt an

```
⚠ Derselbe Blocker tritt erneut auf – Schleife abgebrochen.
```

**Ursache:** Der Coder kann einen bestimmten Blocker oder Concern nicht beheben — z.B.
weil die Aufgabe einen Widerspruch enthält oder ein externes System fehlt.

**Lösung:** Manuell eingreifen:
```
/judge  ← Judge-Bericht lesen
```
Dann den Blocker analysieren und entweder:
- `/fix Ignoriere Blocker X, das ist nicht Teil dieser Aufgabe`
- Den Code selbst anpassen und dann `/fix` aufrufen
- Die Aufgabe in TASK.md präzisieren
- Bei komplexen Aufgaben mit mehr Runden wiederholen: `/optimize --continue --rounds 5`

Falls der Judge wiederholt Concerns findet, die du akzeptierst:
```
/optimize --continue --approve-concerns
```

### Server läuft, aber pi wechselt nicht das Modell

**Ursache:** `models.json` oder `settings.json` wurde nach einer Änderung nicht neu deployt.

**Lösung:**
```bash
cd ~/pi_coder
./install_servers_and_pi_coder_extension.sh
# Dann /reload in pi agent
```

### "Neues Projekt" wechselt nicht das Verzeichnis

Das ist gewollt — pi-Sessions sind an ihr Startverzeichnis gebunden.
Nach `/new_project <pfad>` im Terminal:
```bash
cd <pfad>
pi
```