Phase continuity brief — ciągłość między sesjami

Po co

Jedna sesja Claude'a = jeden kontekst w pamięci. Następna sesja = pustka. Bez briefa kolejny agent spędza 20 minut szukając, "gdzie skończyliśmy". Z briefem startuje w 2 minuty.

Kiedy uruchomić

Przed końcem sesji, gdy:

• Faza została zamknięta (DoD spełnione) → utwórz brief dla Phase N+1
• Sesja kończy się w trakcie fazy → zaktualizuj istniejący brief Phase N
• Zmieniła się strategia / kolejność / credentials → brief musi to odzwierciedlać

Lokalizacja

docs/session-briefs/next-session-phase{N}-brief.md

Commituj do repo (w branchu roboczym feature/*, nie main). Gitignorowane pozostają tylko pliki z creds — brief pokazuje ścieżki do creds, nie same wartości.

Struktura (template)

# Briefing dla nowej sesji — <Project> Phase {N}

> **Wkleij na start**: "Jestem nową sesją Claude dla <Project>. Przeczytaj `docs/session-briefs/next-session-phase{N}-brief.md` i działaj zgodnie z nim."
>
> Aktualizacja: **YYYY-MM-DD** po <co właśnie zamknięto>.

---

## 1. Kolejność czytania (5 min, ZANIM cokolwiek zrobisz)

1. **`CLAUDE.md`** (repo root, auto-loaded) — 6 zasad nienegocjowalnych
2. **Phase spec** (link zewnętrzny) — DoD Phase {N}
3. **Relevant ADRs** (linki) — ADR-XXX, ADR-YYY
4. **`docs/architecture/<plik>.md`** — lokalne dokumenty architektoniczne
5. **`.env.*.local`** — fallback dla connection strings

---

## 2. Gdzie jesteśmy (TL;DR) — stan YYYY-MM-DD

### Zamknięte:
- **Phase {N-1} — DONE**:
  - <kluczowy commit/merge>
  - <migracja, feature flag>
  - <test env live: curl .../health → ...>
- **Release v{X.Y.Z}**:
  - <co poszło live, co zostało>

### Branch topology:
- **`main`** — `<sha>` (v{X.Y.Z}, <co zawiera>)
- **`feature/<name>`** — `<sha>` (Phase {N-1} + main merged = ma wszystko)

### Strategia:
- **Rolling merge dla <X> (low-risk)**: <opis>
- **Big-bang dla <Y> (high-risk)**: <opis>, merge do main po wszystkich fazach DoD
- **Test env ≠ prod env**: <ID test>, <ID prod>

---

## 3. Kluczowe insights / gotchas (oszczędzisz sobie godzin)

### <Gotcha 1 nagłówek>
<Opis konkretny — URL / komenda / error message / workaround>

### <Gotcha 2 nagłówek>
<Opis>

### Decision prompts (harness)
Gdy pytasz użytkownika o wybór — **każda opcja musi mieć 3 linie**:
1. Co fizycznie zrobię (1 linia)
2. Na co wpływa (1 linia — prod/test/UI/DB/cost/irreversible)
3. Trade-off (1 linia — co zyskujemy/tracimy/ile trwa)

Max 3–5 linii per opcja + 1-linia TL;DR rekomendacji.

### Credentials
Wszystkie values w `.env.<env>.local` (repo root, gitignored).

---

## 4. Pierwsze zadanie — Phase {N} start

### Cel (z Phase spec)

<1–2 zdania — co mamy osiągnąć w tej fazie>.

### Precyzyjna mapa plików

| Plik | Co robi | Status |
|---|---|---|
| `<path/to/file>` | <opis> | ✅ SCAFFOLDED (commit `<sha>`) / ⚠ PARTIAL / ⏭ TODO |

### Plan rozbicia fazy na commity (propozycja)

1. **`<plik.sql>`** — migration, idempotent
2. **`<plik.ts>`** — service
3. **`<plik.ts>`** — feature flag + endpoint
4. **Golden set fixture + bench test** — weryfikacja
5. ...

### Phase {N} DoD

- [ ] <konkretny warunek>
- [ ] <konkretny warunek>
- [ ] <konkretny warunek>

### Otwarte ADRs

- **ADR-XXX** — <co dotyczy, kiedy rozstrzygnąć>

---

## 5. Phase {N+1..N+3} rough refs (dla kolejnych sesji)

<Krótkie mapy plików dla kolejnych faz — bez szczegółów, tylko pliki które się pojawią>

---

## 6. Infra quick-check (uruchom przed pierwszym commitem)

\`\`\`bash
git switch <feature-branch> && git pull
curl -s <backend-test-url>/health
psql "<pooler-url>" -c "SELECT ..."
\`\`\`

Jeśli wszystko zielone → plan Phase {N} do użytkownika → czekasz GO → kodujesz.

---

## 7. Harness (krótki reminder)

1. Plan przed kodem (3–5 bullet + GO)
2. Weryfikacja przed zamknięciem (build + test run)
3. Jedna sprawa na commit
4. Dyscyplina faz
5. Read before edit
6. Tool failed → STOP

---

## 8. Po Phase {N} zamknięciu

Utwórz `docs/session-briefs/next-session-phase{N+1}-brief.md` z analogicznym template.

---

## 9. Źródła prawdy

| Co | Gdzie |
|---|---|
| Harness Claude | `CLAUDE.md` |
| Roadmap + DoD | <link zewnętrzny> |
| Decyzje architektoniczne | <link zewnętrzny> |
| Credentials | `.env.<env>.local` |
| Source code | `<feature-branch>` |

Anty-wzorce (NIE rób tego)

• "Ogólny brief" — "będziemy pracować nad fazą 2" bez map plików, bez DoD, bez quick-check. Bezużyteczny.
• Copy-paste starego briefa — nie odświeżony, mylący. Lepszy brak niż zdezaktualizowany.
• Brief w pamięci użytkownika — "powiem Ci na starcie co dalej". Następna sesja nie widzi poprzedniej konwersacji.

Co robić, jeśli brief jest nieaktualny

Nowa sesja znajdzie rozbieżność (np. commit sha w briefie ≠ git log). Zanim cokolwiek zrobisz:

1. git log -10 --oneline + git status
2. Zaktualizuj brief najpierw (commit "chore: update phase brief")
3. Dopiero potem zacznij pracę

Brief to kontrakt między sesjami. Dbaj o niego jak o produkcyjny dokument.