stac-troubleshooter

Diagnose Stac build, deploy, rendering, caching, and navigation issues using repeatable checks. Use when users report stac build finding no screens, deploy mismatches, runtime unknown widget/action errors, cache staleness, or migration regressions.

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.