Lekcja 21 · Faza 2 · Pełna mapa użycia — bez quizu

Kompletna mapa: jak i kiedy używać każdego z 17 skilli

Lekcje 13–20 nauczyły Cię sześciu kroków głównego cyklu jeden po drugim. Ta lekcja jest inna: to jeden gęsty przewodnik użytkowy po wszystkich 17 skillach naraz — dokładna komenda, moment użycia i mechanika każdego, w tym tych, których jeszcze nie omawialiśmy osobno (triage, domain-modeling, handoff, to-prd, writing-great-skills, ask-matt). Bez pytań sprawdzających — to materiał referencyjny, do którego wracasz, gdy nie pamiętasz, po który skill sięgnąć.

Najpierw: model-invoked kontra user-invoked

Zanim przejdziesz przez mapę, jedna rzecz techniczna, decydująca o tym, jak w ogóle wywołasz dany skill. Skill z frontmatterem disable-model-invocation: true odpala się wyłącznie, gdy sam wpiszesz jego nazwę (np. /triage) — Claude nigdy nie sięgnie po niego sam, nawet gdy pasuje do sytuacji. Skill bez tej flagi jest model-invoked: Claude może go uruchomić sam, rozpoznając kontekst z opisu w jego description.

Szybka tabela — wszystkie 17 skilli + teach

Precondition — zanim zaczniesz cokolwiek

/setup-matt-pocock-skills — omówiony w Lekcji 13. Skrót: odkrywa lub ustala issue tracker, etykiety triage i układ dokumentów domenowych, zanim jakikolwiek inny skill z tego pakietu założy, że to już istnieje. Uruchamiasz raz na repozytorium.

Główny przepływ: pomysł → wdrożenie

ask-matt nazywa to "main flow" — trasą, którą podróżuje większość pracy. Poniżej dokładny opis każdego kroku, z rozgałęzieniami.

Krok 1 — ostrzenie pomysłu: trzy warianty jednego prymitywu

Pod spodem wszystkich trzech leży ten sam /grilling — wywiad pytanie-po-pytaniu, jedno pytanie naraz, z rekomendowaną odpowiedzią przy każdym, eksplorującym kod zamiast pytać, gdy da się coś sprawdzić w repo. Różnica jest tylko w tym, co ten wywiad robi z ustaleniami:

Więcej o samym mechanizmie grillowania i trzech warunkach ADR: Lekcja 14.

Krok 2 (opcjonalny branch) — pytanie wymaga uruchomienia kodu

Jeśli podczas grillowania trafisz na pytanie, którego nie da się rozstrzygnąć samą rozmową — model stanu, logika biznesowa, wygląd UI, który trzeba zobaczyć — ask-matt każe zboczyć z głównego wątku, zamiast zgadywać:

/handoff                    → zapisuje kontekst do pliku w katalogu tymczasowym
  (otwórz NOWĄ sesję, wskaż jej ten plik)
/prototype                  → odpowiada na JEDNO pytanie wyrzucalnym kodem
  (wróć do oryginalnej sesji)
/handoff                    → z tej sesji, znów zapisuje wniosek
  (zreferuj wniosek z powrotem w oryginalnym wątku grillowania)

/handoff jest tu użyty w obie strony — to most między dwoma oknami kontekstu, nie kontynuacja w miejscu. Szczegóły /prototype (dwie gałęzie LOGIC.md/UI.md, sześć zasad, zasada "wyrzucasz kod, zostawiasz odpowiedź"): Lekcja 16.

/handoff — most między sesjami, dokładniej

To jedyny skill, który nie kontynuuje rozmowy — kompresuje ją do pliku Markdown w katalogu tymczasowym systemu (nigdy w repo) i zakłada, że otworzysz zupełnie nową sesję, wskazując jej ten plik. Trzy szczegóły, które łatwo przeoczyć:

• Dokument zawiera sekcję "suggested skills" — sugestię, po które skille powinna sięgnąć kolejna sesja, nie tylko streszczenie.
• Nie duplikuje treści, która już istnieje w innym artefakcie (PRD, plan, ADR, issue, commit, diff) — odsyła do niego przez ścieżkę/URL zamiast kopiować.
• Redaguje dane wrażliwe — klucze API, hasła, dane osobowe — zanim cokolwiek zapisze.

Przyjmuje argument opisujący, do czego posłuży następna sesja (argument-hint we frontmatterze) — im dokładniejszy opis, tym trafniej dobrana zawartość dokumentu.

Krok 3 (branch) — czy to build na wiele sesji?

/to-prd — synteza, nie wywiad

W przeciwieństwie do /grill-with-docs, ten skill nie zadaje pytań — bierze to, co już ustaliliście w rozmowie, i syntetyzuje w PRD wg stałego szablonu (Problem Statement, Solution, długa lista User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes), po czym publikuje go na issue tracker z etykietą ready-for-agent. Zanim to zrobi, proponuje seamy testowe — najwyżej możliwe w kodzie, w idealnym przypadku jeden — i każe Ci je potwierdzić. Zasada z to-issues dotycząca braku ścieżek plików/snippetów w treści obowiązuje też tutaj, z tym samym wyjątkiem: snippet z prototypu, jeśli koduje decyzję precyzyjniej niż proza (maszyna stanów, reducer, kształt schematu).

/to-issues i /tdd — już poznane

Cięcie na tracer bullets: Lekcja 15. Pętla red-green z uzgadnianiem seamów: Lekcja 17.

/implement — silnik napędzający pojedynczy issue

To skill, który faktycznie wykonuje pracę opisaną w PRD albo w konkretnym issue. Jego cała treść mieści się w czterech krokach: użyj /tdd tam, gdzie to możliwe, na wcześniej uzgodnionych seamach; uruchamiaj typechecking i pojedyncze pliki testowe regularnie w trakcie pracy, a pełny zestaw testów raz na koniec; po skończonej pracy uruchom /code-review; na końcu commituj na bieżącym branchu. To właśnie ten skill wypełnia sobą pętlę "dla każdego issue z osobna" z głównego przepływu — /tdd i /code-review, których już się nauczyłeś, są jego składowymi, nie odrębnymi krokami do ręcznego sklejania.

Kontekst przez cały główny przepływ

ask-matt stawia twardą zasadę higieny kontekstu: kroki 1–3 (grillowanie → PRD → issues) mają zostać w jednym, nieprzerwanym oknie kontekstu — bez /compact ani /clear — żeby grillowanie, PRD i issues budowały się na tym samym rozumowaniu. Dopiero każdy /implement zaczyna od zera, pracując tylko z treścią jednego issue. Granicą jest tzw. smart zone — okno (~120k tokenów na najlepszych modelach), w którym model wciąż rozumuje ostro. Jeśli sesja zbliża się do tej granicy przed /to-issues, zasada mówi: nie pchaj dalej na zdegradowanej uwadze — użyj /handoff i kontynuuj w nowym wątku, zamiast kompaktować w środku fazy.

On-ramps — sytuacje, które generują pracę i wpadają na główny przepływ

/triage — kolejka spraw, których nie stworzyłeś sam

Zasada odróżniająca go od to-issues: triage jest tylko dla zgłoszeń, których nie stworzyłeś Ty — bug reporty, prośby o funkcje, cokolwiek, co przychodzi "na surowo" z zewnątrz. Issues wyprodukowane przez /to-issues są już agent-ready, więc się ich nie triażuje. Jeśli repo traktuje zewnętrzne pull requesty jako powierzchnię zgłoszeń, triage obejmuje też je — PR to po prostu "issue z podpiętym kodem", ta sama maszyna stanów.

Dwie kategorie ról (bug/enhancement) i pięć ról stanu (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). Proces na konkretnym zgłoszeniu:

1. Zbierz kontekst — treść, komentarze, poprzednie notatki triage, eksploracja kodu; dwa sprawdzenia: czy to już zaimplementowane (po pojęciu domenowym, nie po słowach zgłoszenia), i czy podobna prośba nie została już wcześniej odrzucona (.out-of-scope/*.md).
2. Zarekomenduj kategorię i stan, z uzasadnieniem, i czekaj na decyzję maintainer­a.
3. Zweryfikuj — dla buga: odtwórz go z kroków zgłaszającego; dla PR-a: sprawdź, czy diff faktycznie robi to, co deklaruje.
4. Grilluj, jeśli trzeba — uruchamia /grilling + /domain-modeling razem, jedno pytanie naraz.
5. Zastosuj wynik — brief dla agenta (ready-for-agent), notatki i pytania do zgłaszającego (needs-info), albo zamknięcie z odpowiednim uzasadnieniem (wontfix: już zaimplementowane / odrzucone jako bug / odrzucone jako enhancement, z wpisem do .out-of-scope/).

Każdy komentarz czy issue wystawiony podczas triage musi zaczynać się od jawnego zastrzeżenia: > *This was generated by AI during triage.* — to nie jest opcjonalne.

/diagnosing-bugs — już poznane w praktyce

Pełne sześć faz (feedback loop → reprodukcja → hipotezy → instrumentacja → fix + test regresyjny → cleanup) rozpisane jako diagram w Przepływie C: Referencja: podsumowanie i diagramy. ask-matt dodaje jedno doprecyzowanie: to skill na trudne błędy — te odporne na pierwszy rzut oka, przelotowe flaki, regresje wkradające się między dwoma znanymi-dobrymi stanami. Jego post-mortem przekazuje dalej do /improve-codebase-architecture, gdy prawdziwym wnioskiem jest brak dobrego seamu do przypięcia buga.

Zdrowie kodu — nie feature work, tylko utrzymanie

/improve-codebase-architecture — trzy fazy (Explore → raport HTML poza repo → grillowanie wybranego kandydata), szczegółowo w Lekcji 19. ask-matt nazywa go dokładnie: "the survey that finds the candidates" — surveyem, który znajduje kandydatów; wybranie jednego generuje pomysł, który wraca na główny przepływ w punkcie /grill-with-docs. To zamyka pętlę: utrzymanie architektury nie jest ślepą uliczką, tylko wejściem z powrotem do kroku 1.

Słownictwo pod spodem — dwa modele-invoked, każdy jedyne źródło prawdy dla swojego słownika

/domain-modeling — aktywna dyscyplina, nie tylko czytanie

Różnica, którą łatwo przegapić: samo czytanie CONTEXT.md po słownictwo nie jest tym skillem — to nawyk, który może zrobić dowolny inny skill jednym zdaniem. /domain-modeling to sytuacja, w której zmieniasz model domeny, nie tylko z niego korzystasz. Cztery konkretne ruchy, wszystkie na żywo, w trakcie rozmowy:

• Wyzwij niespójność ze słownikiem — gdy użyty termin koliduje z definicją w CONTEXT.md, zapytaj wprost, które znaczenie obowiązuje.
• Wyostrz mgliste sformułowanie — "account" robiące trzy różne prace to sygnał, żeby zapytać, o który dokładnie obiekt chodzi.
• Testuj konkretnymi scenariuszami — wymyślaj przypadki brzegowe, które zmuszają do precyzji na granicy dwóch pojęć.
• Konfrontuj z kodem — jeśli deklaracja "jak coś działa" nie zgadza się z tym, co robi kod, powiedz to na głos.

Rozstrzygnięcia trafiają do CONTEXT.md od razu, nie zbiorczo na koniec. CONTEXT.md ma być czystym glosariuszem — zero szczegółów implementacyjnych, zero traktowania go jak spec czy notatnik. ADR-y (ten sam plik docs/adr/, który znasz z Lekcji 14) są oferowane tylko, gdy spełnione są jednocześnie trzy warunki: trudno odwracalne, zaskakujące bez kontekstu, i wynik prawdziwego kompromisu. Repo z wieloma kontekstami domenowymi ma plik CONTEXT-MAP.md w korzeniu, wskazujący, gdzie leży CONTEXT.md każdego z nich.

/codebase-design — już poznane

Pełny słownik (module, interface, depth, seam, adapter, leverage, locality) i test usunięcia: Lekcja 18, pełny glosariusz w osobnej referencji. Zapamiętaj z ask-matt jedną rzecz: to "bench", na którym projektujesz kształt kandydata już wybranego przez /improve-codebase-architecture — ten drugi tylko znajduje kandydatów, ten pierwszy je projektuje.

/code-review — już poznane

Dwie osie, dwa równoległe subagenty general-purpose, stały baseline 12 zapachów Fowlera z zasadą "repo wygrywa": Lekcja 20. ask-matt potwierdza, że można go uruchomić samodzielnie, poza pełnym cyklem — "whenever you want to review a branch or PR against a fixed point".

Standalone — poza głównym przepływem, ale zawsze dostępne

/grill-me — już opisane wyżej

Patrz tabela w sekcji "Krok 1". Jedyna różnica względem statusu standalone: reaguje na dowolny plan spoza repozytorium, nie tylko na wątek, który akurat zboczył z głównego przepływu.

/prototype — już poznane

Pełny opis dwóch gałęzi (LOGIC.md/UI.md) i sześciu wspólnych zasad: Lekcja 16.

/teach — meta: skill, który prowadzi tę właśnie lekcję

Warto go tu wymienić, bo też pochodzi z pakietu Matta Pococka, mimo że nie jest częścią cyklu inżynierskiego — służy do nauki koncepcji na przestrzeni wielu sesji, traktując bieżący katalog jako stanowy workspace. Właśnie dlatego ten cały workspace /teach zachowuje historię (numerowane lekcje, `learning-records/`) zamiast zaczynać za każdym razem od zera.

/writing-great-skills — referencja do pisania własnych skilli

Nie jest krokiem procesu — to zbiór zasad, po które sięgasz, gdy piszesz lub edytujesz skill (własny, albo jeden z tych 17, jeśli kiedyś będziesz go dostrajać). Kluczowe pojęcia:

• Przewidywalność jako cel nadrzędny — chodzi o to, żeby agent za każdym razem szedł tym samym procesem, nie o identyczny wynik.
• Model-invoked kontra user-invoked (opisane na górze tej lekcji) — to właśnie stąd pochodzi ten podział.
• Drabina informacji: krok w SKILL.md (natychmiast potrzebny) → referencja w SKILL.md (na żądanie) → referencja zewnętrzna w osobnym pliku (ładowana tylko, gdy odsyłacz "strzeli"). Przykład, który już widziałeś: codebase-design chowa pełne definicje w osobnym GLOSSARY.md.
• Leading words — zwarte pojęcia, które model już zna z treningu (np. "tracer bullet", "seam", "red"), powtarzane w treści skilla, żeby zakotwiczyć całe zachowanie w kilku tokenach zamiast je za każdym razem opisywać od nowa.
• Cztery tryby porażki do diagnozowania cudzego (albo własnego) skilla: przedwczesne zakończenie (agent kończy krok, zanim jest faktycznie zrobiony), duplikacja (to samo znaczenie w dwóch miejscach), osad (stare warstwy, które nikt nie odważył się usunąć), rozrost (skill zwyczajnie za długi, nawet gdy każda linia jest unikalna).

/ask-matt — router, sam ze sobą jako punkt wyjścia

To skill, na którym oparta jest cała ta lekcja. Gdy nie pamiętasz, po który z 17 skilli sięgnąć, wpisujesz /ask-matt i opisujesz sytuację — on wskazuje właściwe miejsce na mapie wyżej. Warto go traktować jako żywy indeks: gdy pakiet się rozrośnie o kolejne skille, to właśnie ten plik będzie źródłem prawdy o tym, gdzie każdy nowy się wpina.