stac-troubleshooter

Stac Troubleshooter to umiejętność do szybkiego diagnozowania problemów w projektach Stac. Uruchamia strukturalne testy, które identyfikują błędy na etapie budowania, wdrażania, renderowania, cache'u i nawigacji. Zwraca dokładne przyczyny problemów, komendy do naprawy i kroki weryfikacji. Przydatne gdy build nie znajduje ekranów, wdrożenie się nie zgadza, pojawiają się błędy nieznanych widżetów, cache jest nieświeży lub migracja zawiera regresje.

1. Przygotuj ścieżkę do katalogu głównego projektu Stac, który chcesz zdiagnozować. Jeśli masz dostęp do komendy, która się nie powiodła, zbierz jej pełne wyjście — przyda się do triażu.

2. Uruchom skrypt diagnostyczny stac_doctor.py, podając ścieżkę do projektu. Skrypt przeprowadzi wstępne testy konfiguracji i struktury projektu, a wynik wyświetli w czytelnym formacie.

3. Jeśli problem dotyczy wyjścia budowania, uruchom check_build_outputs.py z tą samą ścieżką projektu. Skrypt zweryfikuje, czy artefakty budowania znajdują się w oczekiwanym katalogu (domyślnie stac/.build).

4. Na podstawie wyniku diagnostyki określ kategorię problemu: setup, build, deploy, runtime, cache lub nawigacja. Umiejętność zawiera playbooki dla każdej kategorii w katalogu references/ — error-playbooks.md dla błędów ogólnych, cache-debug.md dla problemów z cache'em, navigation-debug.md dla błędów tras i akcji.

5. Zastosuj rekomendowane komendy naprawcze z playbooku. Każda naprawa zawiera dokładną komendę do wykonania i oczekiwany rezultat.

6. Zweryfikuj poprawę, uruchamiając wskazaną komendę weryfikacyjną lub sprawdzając plik konfiguracyjny. Jeśli problem dotyczy migracji JSON-to-Dart, skonsultuj migration-cheatsheet.md dla mapowania pól.