---
name: dev-mate
description: >-
  Orkiestracja komend CLI AI Mate do diagnozy runtime i introspekcji aplikacji:
  analiza logów Monolog, profilera Symfony, listy serwisów DI oraz sanity
  checków środowiska przez entrypoint repo wyznaczony przez `resolve_tool_cmd`.
  Użyj, gdy trzeba zebrać ustrukturyzowane dowody przed implementacją, review
  albo analizą błędu.
shared_files:
  - _shared/references/runtime-collaboration-guidelines.md
  - _shared/scripts/env-load.sh
---

# $dev-mate

## Reguły rozwiązywania ścieżek
- Stosuj globalny kontrakt ścieżek z root `AGENTS.md`.

## Priorytet zasad (globalny kontrakt)
1. Instrukcje systemowe/developerskie środowiska
2. `./AGENTS.md` i dokumenty z `docs_map`
3. Bieżący `SKILL.md`
4. Pliki wskazane w `shared_files`

## Cel
Użyć komend CLI AI Mate jako warstwy diagnostycznej do zbierania ustrukturyzowanych dowodów z logów, profilera, kontenera DI i środowiska uruchomieniowego. Skill ma pomóc przejść od potrzeby diagnostycznej do konkretnego zestawu komend, a potem do kolejnego kroku w repo.

## Intencje
Użyj tego skilla, gdy pojawia się potrzeba:
- zrozumienia ostatniego błędu runtime albo wyjątku bez ręcznego grep-owania wszystkich logów,
- powiązania problemu z konkretnym requestem, tokenem profilera, statusem HTTP albo route,
- sprawdzenia, czy serwis Symfony istnieje, jaki ma class albo czy kontener zbudował dany alias,
- potwierdzenia, czy problem wygląda na środowiskowy, a nie stricte kodowy,
- zebrania szybkich dowodów runtime przed wejściem w `$code-implement`, `$review-quick` albo zwykłe czytanie kodu.

## Źródło komend
1. Załaduj helper `env-load.sh` wskazany w `shared_files`.
2. Wyznacz `<MATE_CMD>` wyłącznie przez `resolve_tool_cmd mate`.
3. Jeśli potrzebujesz wrócić do standardowych entrypointów repo, wyznacz je tak samo przez `resolve_tool_cmd` zamiast ręcznie składać ścieżki z `BIN_PATH`.

## Zakres
Skill obejmuje:
- dobór właściwej komendy CLI AI Mate do potrzeby diagnostycznej,
- uruchomienie komendy z możliwie wąskim zakresem danych,
- interpretację wyniku w kontekście decyzji inżynierskiej,
- wskazanie następnego kroku w repo po zakończeniu diagnostyki.

## Minimalny workflow
1. Ustal, czy problem dotyczy runtime, a nie tylko statycznego kodu lub ścieżki pliku.
2. Jeśli nie znasz parametrów narzędzia, użyj `mcp:tools:inspect`.
3. Uruchom `mcp:tools:call` z możliwie wąskim zakresem danych.
4. Zawęź wynik i wróć do kodu, diffów lub dokumentacji z konkretnym tropem.

## Reguła wyboru narzędzi
- Jeśli pytanie dotyczy kodu statycznego, ścieżki pliku, symbolu, konfiguracji w repo albo diffu, najpierw użyj standardowych narzędzi repo.
- Jeśli pytanie dotyczy runtime, logów, requestu, profilera, skompilowanego kontenera albo środowiska wykonania, najpierw użyj komend AI Mate.
- Jeśli nie masz pewności, zacznij od najtańszego źródła prawdy i nie używaj AI Mate tylko „na wszelki wypadek”.

## Narzędzia bazowe
Jeśli nie znasz dostępnych narzędzi albo ich parametrów:
- użyj `<MATE_CMD> debug:extensions --show-all`, aby potwierdzić aktywne rozszerzenia,
- użyj `<MATE_CMD> mcp:tools:list`, aby zobaczyć listę narzędzi,
- użyj `<MATE_CMD> mcp:tools:inspect <tool-name>`, aby sprawdzić interfejs konkretnego narzędzia.

Preferuj wywołania:
- `<MATE_CMD> mcp:tools:call <tool-name> '<json>' --format=json`

Reguła wykonawcza:
- jeśli parametrów narzędzia nie da się bezpiecznie wywnioskować z prompta, najpierw użyj `mcp:tools:inspect`, a dopiero potem `mcp:tools:call`,
- jeśli wynik `mcp:tools:call` jest zbyt szeroki, nie powtarzaj tego samego wywołania bez zmian; zawęź parametry albo zmień scenariusz.

## Scenariusze

### 1. Błąd runtime lub wyjątek w logach
Sygnały użycia:
- użytkownik mówi o błędzie 500, wyjątku, ostrzeżeniu, regresji po requestach albo problemie widocznym w logach,
- masz fragment komunikatu błędu, poziom logu, kanał albo identyfikator z kontekstu logów.

Przykładowe wejścia:
- „sprawdź ostatnie błędy w logach”
- „przeszukaj logi po `AccessDeniedException`”
- „pokaż warningi z dev logów”
- „znajdź logi dla `request_id=...`”
- „czy w logach widać, czemu ten request wywala 500?”

Potrzeba:
- szybko zawęzić źródło problemu i zebrać dowody zanim zaczniesz zmieniać kod.

Kolejność narzędzi:
1. `monolog-list-files`, jeśli nie wiesz jeszcze, jakie logi są dostępne.
2. `monolog-tail`, jeśli chcesz zobaczyć najnowsze wpisy z danego środowiska.
3. `monolog-by-level`, jeśli znasz poziom logu, np. `error` albo `warning`.
4. `monolog-search`, jeśli masz tekst błędu, nazwę wyjątku, fragment komunikatu albo route.
5. `monolog-search-regex`, jeśli wzorzec jest nieregularny i zwykły search daje zbyt dużo szumu.
6. `monolog-context-search`, jeśli masz `request_id`, `tenant_id`, `user_id` albo inny klucz kontekstowy.

Jak zawężać wynik:
- jeśli użytkownik podał `request_id`, `tenant_id`, `user_id` albo inny klucz kontekstowy, preferuj `monolog-context-search` przed pełnym search tekstowym,
- ustaw `environment`, gdy wiesz, którego środowiska dotyczy problem,
- ustaw `channel`, `level` i `limit`, żeby nie zalewać kontekstu,
- preferuj najpierw wąskie zapytanie, a dopiero potem poszerzaj zakres.

Co zrobić z wynikiem:
- wyłuskaj stabilne fakty: typ błędu, miejsce wystąpienia, request/context identifiers, powtarzalność,
- jeśli wynik wskazuje konkretny request lub token profilera, przejdź do scenariusza „Profiler Symfony”,
- jeśli wynik wskazuje konkretną klasę, handler, komendę albo serwis, wróć do kodu i potwierdź to przez `rg`, diff lub odczyt pliku.
- jeśli wynik jest pusty, sprawdź najpierw środowisko logów (`environment`, `channel`, `level`) zamiast od razu zakładać, że problem nie wystąpił.

### 2. Analiza requestu i danych z profilera
Sygnały użycia:
- problem dotyczy konkretnego requestu HTTP, statusu odpowiedzi, route, czasu wykonania albo wyjątków z web profilu,
- chcesz potwierdzić zachowanie aplikacji po realnym wywołaniu zamiast wnioskować tylko z kodu.

Przykładowe wejścia:
- „sprawdź ostatni request w profilerze”
- „znajdź w profilerze requesty do `/login` z 500”
- „przeanalizuj profil dla tego tokena”
- „zobacz, co profiler pokazuje dla ostatniego błędu”
- „sprawdź ostatnie profile dla POST-a na ten endpoint”

Potrzeba:
- zobaczyć, co faktycznie wydarzyło się w request/response cycle i czy profiler ma już ślad problemu.

Kolejność narzędzi:
1. `symfony-profiler-latest`, gdy chcesz ostatni request.
2. `symfony-profiler-search`, gdy znasz route, metodę, status albo zakres czasu.
3. `symfony-profiler-list`, gdy chcesz szybko przejrzeć kilka ostatnich profili i wybrać właściwy.
4. `symfony-profiler-get`, gdy masz token i chcesz dane jednego konkretnego profilu.

Jak zawężać wynik:
- użyj `route`, `method`, `statusCode`, `from`, `to` i `limit`,
- jeśli masz token z wcześniejszej analizy, przejdź od razu do `symfony-profiler-get`.

Co zrobić z wynikiem:
- ustal, czy problem jest odtwarzalny i który profil jest właściwym punktem odniesienia,
- potraktuj `resource_uri` jako wskaźnik do dalszej analizy, ale decyzje nadal opieraj na danych zwróconych przez tool i kodzie repo,
- jeśli profiler pokazuje wyjątek, request metadata albo kolektor prowadzący do konkretnego obszaru, wróć do kodu i dokumentacji tego obszaru.
- jeśli profiler nic nie zwraca, potraktuj to jako sygnał do sprawdzenia, czy problem był faktycznie odtworzony w środowisku z aktywnym profilerem.

### 3. Introspekcja kontenera i zależności DI
Sygnały użycia:
- problem dotyczy braku serwisu, aliasu, autowiringu, dekoratora, tagów albo podejrzanego wiring-u kontenera,
- użytkownik pyta, czy dany serwis istnieje albo jaka klasa stoi za danym service id.

Przykładowe wejścia:
- „czy serwis `foo.bar` istnieje w kontenerze?”
- „jaką klasę ma ten service id?”
- „sprawdź, czy kontener zbudował alias dla tej usługi”
- „czy ten handler jest widoczny w DI?”
- „pokaż, czy autowiring ma tu z czego skorzystać”

Potrzeba:
- potwierdzić stan skompilowanego kontenera bez zgadywania na podstawie samych plików konfiguracyjnych.

Narzędzie:
1. `symfony-services`

Jak używać:
- używaj tego narzędzia tylko wtedy, gdy pytanie dotyczy faktycznie skompilowanego kontenera, a nie samego znalezienia definicji w repo,
- preferuj format JSON, bo narzędzie może zwrócić bardzo szeroką listę,
- po otrzymaniu wyniku filtruj po stronie agenta do konkretnego service id, namespace albo klasy i do rozmowy wnoś tylko zawężony fragment,
- gdy pytanie dotyczy wyłącznie znalezienia definicji usługi, rozważ najpierw zwykły odczyt repo, a `symfony-services` użyj jako potwierdzenia runtime.

Co zrobić z wynikiem:
- ustal, czy serwis istnieje i jaką ma klasę,
- potraktuj wynik jako dowód stanu kontenera, a nie jako zamiennik definicji w repo,
- po znalezieniu serwisu wróć do `config/`, `services.yaml`, atrybutów albo definicji klas i potwierdź przyczynę problemu.

### 4. Szybki sanity check środowiska Mate
Sygnały użycia:
- problem wygląda na środowiskowy,
- chcesz potwierdzić wersję PHP, dostępność rozszerzeń albo podstawowe informacje o runtime przed dalszą diagnozą.

Przykładowe wejścia:
- „sprawdź wersję PHP w runtime”
- „czy to środowisko ma potrzebne extensiony?”
- „jaki to system i na czym to chodzi?”
- „potwierdź, czy problem nie wynika z runtime”

Potrzeba:
- odróżnić problem aplikacyjny od problemu środowiskowego możliwie małym kosztem.

Kolejność narzędzi:
1. `php-version`
2. `php-extensions`
3. `operating-system`
4. `operating-system-family`

Co zrobić z wynikiem:
- jeśli wynik potwierdza podejrzenie środowiskowe, wróć do entrypointów repo, kontenerów i konfiguracji,
- jeśli środowisko wygląda poprawnie, zawęź diagnozę do logów, profilera albo kodu.

## Zasady interpretacji
- Komendy AI Mate dostarczają dowody runtime i introspekcji, ale nie zastępują czytania kodu, diffów i dokumentacji.
- Każdy wniosek mapuj do konkretnego problemu: log/error, request/profile, serwis/DI albo środowisko.
- Gdy wynik jest pusty, zbyt szeroki albo nie rozstrzyga problemu, zawęź parametry albo wróć do standardowego workflow repo.

## Następny krok po użyciu skilla
Po zebraniu danych z komend AI Mate zawsze wybierz jedno z działań:
- wróć do kodu i dokumentacji, jeśli masz już konkretny obszar do zbadania,
- przejdź do `$code-implement`, jeśli diagnoza wskazała potrzebną zmianę,
- przejdź do `$review-quick`, jeśli diagnoza dotyczy oceny ryzyka lub regresji,
- wróć do zwykłych entrypointów repo wyznaczonych przez `resolve_tool_cmd`, jeśli problem wymaga dalszej pracy poza AI Mate.

## Format odpowiedzi
- Wynik: co udało się ustalić.
- Dowody: jakie narzędzia i parametry zostały użyte.
- Następny krok: co zrobić dalej na podstawie otrzymanych danych.