# PAUL — Workflow dla shopPRO

[PAUL](https://github.com/ChristopherKahler/paul) to zestaw komend dla Claude Code, który strukturyzuje pracę nad projektem: planowanie → implementacja → weryfikacja. Działa przez slash-komendy w czacie z Claude.

---

## Jednorazowa inicjalizacja

```
/paul:init
```

Uruchom raz — tworzy plik `.paul/` z konfiguracją projektu (milestones, fazy). Jeśli już zainicjalizowany, pomijasz ten krok.

---

## Nowa funkcja (feature)

### 1. Omów wizję

```
/paul:discuss
```

Claude zadaje pytania, żeby doprecyzować, co dokładnie chcesz zbudować — wynik to jasna definicja przed planowaniem.

### 2. Zbadaj opcje techniczne (opcjonalnie)

```
/paul:discover
```

Przydatne gdy nie jesteś pewny jak zaimplementować coś technicznie — Claude przegląda kod i proponuje podejścia.

### 3. Zaplanuj implementację

```
/paul:plan
```

Tworzy szczegółowy plan z krokami, plikami do zmiany, kolejnością. Zatwierdź plan zanim ruszysz dalej.

### 4. Wykonaj plan

```
/paul:apply
```

Claude implementuje plan krok po kroku, z commitami na każdą fazę.

### 5. Zweryfikuj (UAT)

```
/paul:verify
```

Claude generuje checklistę testów manualnych — punkt po punkcie sprawdzasz czy funkcja działa.

---

## Poprawka błędu (bug fix)

```
/paul:plan-fix
```

Dedykowany flow dla bugów: opisujesz problem → Claude analizuje kod → tworzy plan naprawy → `/paul:apply` wykonuje.

Krótszy wariant dla prostych bugów — możesz też po prostu opisać błąd i użyć `/paul:plan` → `/paul:apply`.

---

## Zarządzanie sesjami

| Komenda | Kiedy |
|---------|-------|
| `/paul:progress` | Sprawdź gdzie jesteś, co dalej |
| `/paul:pause` | Kończysz sesję — tworzy plik handoff |
| `/paul:resume` | Zaczynasz nową sesję — wczytuje kontekst |
| `/paul:handoff` | Generuje dokument przekazania pracy |

---

## Milestones (większe wdrożenia)

Gdy planujesz większą wersję (np. nowy moduł, refactor):

```
/paul:milestone        # Tworzysz nowy milestone
/paul:add-phase        # Dodajesz fazę do milestone
/paul:complete-milestone  # Zamykasz po wdrożeniu
```

---

## Czy PAUL może przejrzeć projekt pod kątem błędów?

Tak, częściowo. Najlepsze podejście:

### Mapowanie kodu

```
/paul:map-codebase
```

Generuje analizę architektury — wyłapuje niespójności, martwy kod, problematyczne zależności.

### Research konkretnego obszaru

```
/paul:research
```

Np. _"Sprawdź czy walidacja zamówień w OrderRepository jest kompletna"_ — Claude przegląda kod i raportuje problemy.

### Ograniczenia

PAUL nie jest narzędziem do statycznej analizy kodu (jak PHPStan czy psalm). Do systematycznego przeglądu błędów lepiej połączyć:

- **PAUL** (`/paul:map-codebase` + `/paul:research`) — problemy architektoniczne, logika biznesowa
- **Testy** (`./test.ps1`) — regresje, złe zachowanie metod
- **PHPStan** (jeśli dodany do projektu) — typy, niezdefiniowane zmienne

---

## Typowy dzień pracy w shopPRO

```
# Rano — wznów kontekst
/paul:resume

# W trakcie — sprawdź co dalej
/paul:progress

# Nowa funkcja lub bug
/paul:discuss   →   /paul:plan   →   /paul:apply   →   /paul:verify

# Na koniec dnia
/paul:pause
```

---

## Dobre praktyki

- Zawsze zatwierdzaj plan (`/paul:plan`) zanim uruchomisz `/paul:apply` — łatwiej zmienić plan niż cofnąć kod
- Po każdym `/paul:apply` odpal testy: `./test.ps1`
- Używaj `/paul:verify` przed mergem — generuje checklistę zamiast zgadywać co przetestować
- Przy bugach najpierw opisz symptom dokładnie, Claude lepiej planuje naprawę mając konkretny przypadek