Reference · Diagramy przepływu

mattpocock/skills: podsumowanie i trzy przepływy pracy

Skrót sześciu kroków głównego cyklu (Lekcje 13–20) plus trzy konkretne ścieżki: rozszerzanie istniejącego modułu, budowa nowej funkcjonalności od zera, i szukanie/łatanie błędów. Każdy krok w diagramach cytuje realny skill z .agents/skills/ — kolejność i rozgałęzienia między nimi to synteza tej analizy, nie dosłowny, jeden dokument źródłowy. Gdzie kolejność jest wprost potwierdzona przez autora, jest tak zaznaczone.

Sześć kroków głównego cyklu (potwierdzone przez README)

#	Skill	Robi	Lekcja
1	setup-matt-pocock-skills	Jednorazowo: issue tracker, etykiety triage, układ dokumentów domenowych	13
2	grill-me / grill-with-docs	Wywiad pytanie-po-pytaniu ostrzący plan; wariant "with docs" aktualizuje CONTEXT.md i ADR-y na żywo	14
3	to-issues	Tnie plan na tracer bullets — pionowe plastry przez wszystkie warstwy naraz	15
4	tdd	Red → green na uzgodnionym seamie, jeden test na cykl, refaktor poza pętlą	17
5	improve-codebase-architecture	Skanuje pod kątem płytkich modułów, raport HTML poza repo, grillowanie wybranego kandydata	19
6	code-review	Standards + Spec równolegle, dwa osobne raporty, bez wspólnego rankingu	20

Narzędzia sytuacyjne (obok głównego cyklu)

Skill	Kiedy sięgnąć
prototype	nierozstrzygnięte pytanie o model stanu albo wygląd UI (Lekcja 16)
codebase-design	słownik do rozmowy o module/interfejsie/seamie (Lekcja 18) — używany przez improve-codebase-architecture
diagnosing-bugs	twardy bug albo regresja wydajności — patrz Przepływ C niżej
triage, ask-matt, handoff, writing-great-skills	zarządzanie kolejką issues, wybór właściwego skilla, przekazanie sesji dalej, pisanie własnych skilli — poza zakresem obecnych lekcji

Przepływ A — nowa funkcjonalność od zera

[setup-matt-pocock-skills]   (raz, na starcie pracy z repo)
        │
        ▼
[grill-with-docs / grill-me]  — ustal plan, uzupełnij CONTEXT.md na żywo
        │
        ├─ pytanie o stan/UI nierozstrzygnięte? ──▶ [prototype] ──┐
        │                                                          │
        ▼◀─────────────────────────────────────────────────────────┘
[to-issues]  — potnij na tracer bullets (pionowe plastry)
        │
        ▼  dla KAŻDEGO issue z osobna:
     [tdd]  — uzgodnij seam → red → green, jeden test na cykl
        │
        ▼
  [code-review]  — Standards + Spec względem tego issue
        │
        ├─ zauważono tarcie architektoniczne? ──▶ [improve-codebase-architecture]
        ▼
     gotowe → kolejny issue z listy

Kroki 1–3 potwierdzone jako sekwencja w README autora (patrz mattpocock/skills). Pętla "tdd → code-review per issue" i rozgałęzienia do prototype/improve-codebase-architecture to synteza na podstawie tego, co poszczególne skille referencjonują nawzajem w swoich SKILL.md.

Przepływ B — rozszerzanie istniejącego modułu

Masz już moduł z ustalonym seamem/interfejsem
        │
        ▼
   [grilling]  — krótki wywiad: co dokładnie się zmienia,
        │        czy istniejący seam nadal pasuje do zmiany
        │
        ├─ moduł płytki / seam nie pasuje ──▶ [improve-codebase-architecture]
        │                                            │
        │◀───────────────────────────────────────────┘ (po pogłębieniu wracasz)
        ▼
  zmiana mieści się w jednym tracer bullecie?
        │
   TAK ─┤                    NIE
        │                     └──▶ [to-issues]  (rozbij na kilka slice'ów)
        ▼
     [tdd]  — nowy test przy ISTNIEJĄCYM seamie, red → green
        │
        ▼
  [code-review]  — Standards + Spec (spec = krótki opis zmiany albo issue)

Różnica względem Przepływu A: seam zwykle już istnieje, więc grill-with-docs (pełny wywiad + dokumentacja) jest zwykle przesadą — wystarcza krótsze grilling. Test z Lekcji 18 ("jeden adapter = hipotetyczny seam, dwa = prawdziwy") pomaga ocenić, czy w ogóle warto tworzyć nowy seam, czy rozszerzyć istniejący.

Przepływ C — szukanie i łatanie błędów

W całości z .agents/skills/diagnosing-bugs/SKILL.md — sześć faz, pomijanych tylko z wyraźnym uzasadnieniem.

Zgłoszono błąd / regresję wydajności
        │
        ▼
Faza 1 — Zbuduj feedback loop (TO JEST ta umiejętność, reszta mechaniczna)
        │   test / curl / CLI / przeglądarka headless / replay traceʼu /
        │   throwaway harness / fuzz / bisekcja / HITL — w tej kolejności prób
        │   Koniec fazy: JEDNA komenda, już uruchomiona, red-capable,
        │   deterministyczna, szybka, uruchamialna bez człowieka
        ▼
Faza 2 — Odtwórz i zminimalizuj
        │   usuwaj elementy repro po jednym, aż każdy pozostały jest
        │   load-bearing (usunięcie któregokolwiek zazieleniłoby loop)
        ▼
Faza 3 — Hipotezy
        │   3-5 rankowanych, KAŻDA falsyfikowalna ("jeśli X, to zmiana Y
        │   usunie błąd") — pokazane użytkownikowi przed testowaniem
        ▼
Faza 4 — Instrumentacja
        │   jedna zmienna na raz; debugger/REPL > targeted logi > NIGDY
        │   "loguj wszystko i grepuj"; każdy log otagowany [DEBUG-xxxx]
        ▼
Faza 5 — Fix + regression test
        │   test PRZED fixem, ale tylko przy poprawnym seamie —
        │   brak poprawnego seamu to SAM W SOBIE finding
        ▼
Faza 6 — Cleanup + post-mortem
        │   oryginalne repro już nie odtwarza się, test regresyjny przechodzi,
        │   logi [DEBUG-...] usunięte, hipoteza która się potwierdziła
        │   opisana w commit/PR message
        ▼
  "Co by temu zapobiegło?" (pytane PO fixie, nie przed)
        │
        └─ odpowiedź = problem architektoniczny ──▶ [improve-codebase-architecture]
                                                       z konkretnym opisem

Kluczowa różnica względem Przepływów A/B: tu nie ma grilling ani to-issues na wejściu — dyscyplina zaczyna się od zbudowania sygnału pass/fail, nie od planowania. Zamknięcie pętli (opcjonalny handoff do improve-codebase-architecture) jest wprost zapisane w SKILL.md tego skilla.