UPDATE

docs/PAUL_WORKFLOW.md

@@ -0,0 +1,150 @@
+# 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
+