Lekcja 23 · Faza 3 · Planowanie wieloetapowe

decision-mapping: planowanie rozciągnięte na wiele sesji

Wszystkie skille z głównego cyklu (Lekcje 13–20) zakładały ciche założenie: pomysł da się dograllować w jednym, nieprzerwanym oknie kontekstu, a potem pociąć na issues. decision-mapping jest na sytuację, w której to założenie pęka — luźny pomysł ma tyle otwartych pytań, że samo ich rozwikłanie wymaga więcej niż jednej sesji agenta, zanim cokolwiek trafi do /to-prd.

Polecane źródło Lokalny plik .agents/skills/decision-mapping/SKILL.md w tym repo.

Artefakt: Decision Map

Jeden zwarty plik Markdown na całe przedsięwzięcie planistyczne, wersjonowany w git obok projektu. To kanoniczny artefakt — cała mapa ładuje się jako kontekst do każdej sesji, więc musi zostać zwarta. Zasoby wytworzone podczas pracy nad ticketem (raport z researchu, prototyp) są linkowane z mapy, nie duplikowane w jej treści.

Mapa składa się z wpisów ("ticketów"), każdy w osobnej sekcji, kluczowany krótkim slugiem w dash-case (np. relational-db, auth-strategy):

## relational-db: Relational Or Non-Relational Database?

Blocked by: <slug>, <slug>
Status: open | in-progress | resolved
Type: Research | Prototype | Grilling | Task

### Question

<pytanie>

### Answer

<odpowiedź>

Ticket jest odblokowany, gdy każdy ticket na jego liście Blocked by ma status resolved. Każdy ticket ma być rozmiaru jednej sesji agenta (~100K tokenów) — to twardy limit projektowy, nie sugestia.

Cztery typy ticketów

Typ	Kiedy	Co produkuje
Research	Wiedza spoza bieżącego katalogu — dokumentacja, API strony trzeciej, baza wiedzy	Markdown-owe podsumowanie jako osobny zasób
Prototype	Pytanie "jak to powinno wyglądać/działać" — trzeba podnieść wiarygodność dyskusji konkretem	Prototyp (przez skill `/prototype`) jako zasób
Grilling	Domyślny przypadek — zwykła rozmowa	Rozstrzygnięcie zapisane wprost w tickecie, przez `/grilling` + `/domain-modeling`
Task	Dosłowna ręczna praca bez niczego do decydowania — przeniesienie danych, rejestracja w usłudze trzeciej	Wykonana praca; odpowiedź zapisuje fakty, od których zależą późniejsze tickety (np. lokalizacja poświadczeń)

Zauważ, że trzy z czterech typów to bezpośrednie wywołania skilli, których już się nauczyłeś — decision-mapping nie wymyśla nowej mechaniki resolwowania, tylko organizuje kiedy po którą sięgnąć.

Fog of war — celowo niekompletna mapa

Mapa jest celowo niekompletna poza granicą znanego. Twoja praca to zbadanie tej granicy (frontier) i rozwiązywanie ticketów, żeby przesunąć ją dalej — węzeł po węźle, aż droga do celu będzie jasna i nie zostanie żaden otwarty ticket.

Kluczowy wniosek: to ten sam kształt problemu co grounding z Lekcji 22 — granica między tym, co już wiadomo, a tym, co dopiero trzeba ustalić — tylko przeniesiona z pojęć czytelnika na decyzje projektowe. Tam beat nie mógł oprzeć się na pojęciu, które nie zostało jeszcze ugruntowane; tutaj ticket nie jest odblokowany, dopóki tickety go blokujące nie są rozwiązane. Różne słowa (grounding kontra fog of war), ten sam mechanizm: pilnowanie granicy między znanym a nieznanym.

Dwie gałęzie: budowa mapy kontra praca nad mapą

Gałąź	Wywołanie	Co się dzieje
Budowa mapy	Użytkownik podaje luźny pomysł	Sesja `/grilling` + `/domain-modeling` wydobywa otwarte decyzje; powstaje nowa mapa — głównie mgła, z zaznaczoną granicą i trywialnymi wpisami rozstrzygniętymi od razu. Budowa mapy to praca jednej sesji — ta sama sesja nie rozwiązuje jeszcze żadnego ticketu.
Praca nad mapą	Użytkownik podaje ścieżkę do istniejącej mapy, opcjonalnie slug ticketu	Cała mapa ładuje się jako kontekst. Bez podanego sluga agent sam wybiera pierwszy odblokowany, otwarty ticket w kolejności dokumentu.

Mechanizm przeciw wyścigom: sesja zajmuje ticket, ustawiając Status: in-progress i zapisując mapę, zanim zacznie jakąkolwiek pracę. Dzięki temu, jeśli użytkownik równolegle otworzy kilka sesji na różnych odblokowanych ticketach, kolejna sesja widzi już zajęty ticket i pomija go zamiast dublować pracę. Po rozwiązaniu: odpowiedź trafia do ciała ticketu, status na resolved, a nowo odkryte tickety dopisywane są z poprawnymi krawędziami Blocked by — jeśli podjęte decyzje unieważniają inne węzły mapy, trzeba je zaktualizować albo usunąć.

Koniec każdej sesji: Next steps do wklejenia

Zasada jest twarda: nigdy więcej niż jeden ticket na sesję, a każda sesja kończy się czyszczeniem kontekstu i otwarciem nowej. Zamiast literalnie wywoływać skill /handoff z Lekcji 21, decision-mapping po prostu kończy się blokiem Next steps gotowym do wklejenia — to inny mechanizm o tym samym duchu ("zamknij kontekst, przenieś się dalej przez plik"), nie to samo wywołanie.

Zostały otwarte tickety — lista odblokowanych ticketów, plus dwie gotowe komendy: jedna do jednej sesji (agent sam wybierze kolejny ticket), i po jednej przypiętej komendzie na każdy odblokowany ticket do uruchomienia równolegle w osobnych oknach.
Nie zostało nic otwartego — mgła cofnięta wystarczająco daleko, mapa gotowa. Rekomendacja: albo wdrażaj bezpośrednio, albo użyj /to-prd, żeby zaplanować wdrożenie na wiele sesji.

decision-mapping kontra to-prd/to-issues — kiedy które

Łatwo je pomylić, bo oba dotyczą planowania na wiele sesji. Różnica leży w tym, co jest niepewne:

to-prd/to-issues (Lekcja 15) zakładają, że wątek grillowania już ustalił, co budować — zadanie to synteza i cięcie na niezależne kawałki implementacji.
decision-mapping wchodzi wcześniej: gdy same pytania (baza relacyjna czy nie, jaka strategia auth) są na tyle rozległe, że ich rozstrzygnięcie samo w sobie wymaga wielu sesji badawczych, prototypowych albo rozmów — zanim jest w ogóle co przekazać do /to-prd.

Mapa jest domenowo-agnostyczna — planuje pracę inżynierską, treść kursu albo cokolwiek innego o tym samym kształcie (sekwencja zależnych od siebie otwartych pytań).

Zadanie praktyczne — zbuduj mapę na prawdziwie niepewnym pomyśle

W swoim prawdziwym projekcie firmowym, na pomyśle, którego jeszcze nie potrafisz opisać jednym zdaniem specyfikacji, wpisz /decision-mapping:

Sprawdź, czy powstała mapa faktycznie jest "głównie mgłą" — z niewieloma trywialnymi wpisami rozstrzygniętymi od razu, nie z gotowym planem.
Otwórz nową sesję i podaj jej ścieżkę do mapy — zaobserwuj, czy agent poprawnie wybiera pierwszy odblokowany ticket bez pytania Cię, który.
Po rozwiązaniu jednego ticketu sprawdź blok "Next steps" — czy komendy faktycznie dają się wkleić 1:1 do nowego okna?

Sprawdź się

1. Kiedy sięgasz po decision-mapping zamiast od razu po to-prd?

to-prd zakłada, że już wiadomo co budować. decision-mapping wchodzi wcześniej — gdy rozstrzygnięcie samych pytań wymaga więcej niż jednej sesji badawczej czy grillowania.

2. Kiedy ticket na mapie jest formalnie "odblokowany"?

Definicja jest wprost strukturalna: ticket jest unblocked dokładnie wtedy, gdy wszystkie tickety wymienione w jego Blocked by mają status resolved.

3. Po co sesja ustawia Status: in-progress i zapisuje mapę PRZED rozpoczęciem pracy nad ticketem?

To mechanizm przeciw wyścigom przy pracy równoległej: zajęcie ticketu przed pracą pozwala innym otwartym sesjom pominąć go zamiast rozwiązywać go drugi raz.

4. Który typ ticketu dobierzesz do pytania "jak dokładnie powinien wyglądać ten ekran ustawień"?

Typ Prototype jest właśnie na pytania "jak to powinno wyglądać/działać" — zamiast dyskutować w próżni, ticket produkuje tani, konkretny artefakt przez skill /prototype.

5. Dlaczego "fog of war" z tej lekcji przypomina "grounding" z Lekcji 22, mimo że to dwa różne słowa?

Różne domeny (pojęcia czytelnika kontra decyzje projektowe), ten sam kształt: kolejny krok może oprzeć się tylko na tym, co już ugruntowane/rozwiązane, nigdy na tym, co wciąż leży za granicą.

Coś niejasne? Zapytaj mnie wprost — mogę pomóc rozstrzygnąć, czy konkretny, niepewny pomysł z Twojego projektu zasługuje na osobną Decision Map, czy wystarczy zwykłe grillowanie.

← Lekcja 22: pipeline pisarski Następna lekcja: loop-me — specyfikowanie automatyzacji →