feedback-page

name

feedback-page

description

Generuje interaktywną stronę HTML do zbierania feedbacku na treści: artykuł, wpis blogowy, newsletter, landing page albo dowolną stronę wygenerowaną przez AI. Użytkownik zaznacza fragmenty myszką, dopisuje komentarze w dymkach i klika "Wyślij", a feedback wraca prosto do Claude (przez lokalny serwer) gotowy do naniesienia poprawek. Użyj ZAWSZE, gdy użytkownik chce "nanieść uwagi", "dać feedback do tekstu/strony", "zaznaczyć i skomentować fragmenty", "podejrzeć jak markdown wygląda na blogu i go poprawić", "zrobić stronę do recenzji treści", albo poprosi o interaktywny podgląd artykułu/strony do komentowania - nawet jeśli nie powie wprost "feedback-page". Działa na plikach .md (renderuje jak na blogu) i .html (wstrzykuje warstwę komentarzy do istniejącej strony).

Feedback Page

Zamienia dowolną treść w interaktywną stronę do zbierania uwag. Użytkownik zaznacza tekst, komentuje w dymku, a komplet uwag wraca do Ciebie gotowy do wdrożenia. Eliminuje rundy "w trzecim akapicie zmień X, a w tabeli Y" - widzisz dokładnie który fragment i jaką ma mieć poprawkę.

Kiedy używać

• Użytkownik napisał/wygenerował treść (artykuł, mail, wpis, landing, stronę z AI) i chce ją zrecenzować zaznaczając fragmenty.
• Chce zobaczyć, jak markdown wyrenderuje się na blogu, i przy okazji nanieść poprawki.
• Mówi "daj mi nanieść uwagi", "chcę skomentować fragmenty", "zrób podgląd do feedbacku".

Jak to działa (architektura)

Dwa kawałki:

1. scripts/build_feedback_page.py - bierze plik wejściowy i produkuje samodzielną stronę HTML z wbudowaną warstwą komentarzy (assets/feedback_layer.html).
   • Wejście .md → renderuje markdown przez marked.js w neutralnym szablonie blogowym (jasne tło, GitHub-style code blocki — bez branding-u, działa na każdej treści).
   • Wejście .html → wstrzykuje warstwę komentarzy przed </body> istniejącej strony, nie ruszając jej wyglądu. Tak komentuje się strony wygenerowane przez AI.
2. scripts/feedback_server.py - serwuje stronę pod http://localhost:PORT/ i nasłuchuje na POST /__fp_submit__. Gdy użytkownik klika "Wyślij", zapisuje feedback do pliku JSON i kończy pracę. Zakończenie procesu w tle automatycznie wznawia Claude Code - czytasz JSON i nanosisz poprawki. Bez kopiuj-wklej.

Strona ma fallback: jeśli serwer nie działa (np. ktoś otworzył sam plik file://), "Wyślij" pobiera feedback.json do Pobranych i kopiuje do schowka. Wtedy czytasz plik z ~/Downloads albo użytkownik wkleja treść.

Procedura

Krok 1: zbuduj stronę

python ~/.claude/skills/feedback-page/scripts/build_feedback_page.py \
  --input /ścieżka/do/tresci.md \
  --title "Tytuł (opcjonalnie, tryb md)"

Skrypt wypisuje ścieżkę wygenerowanej strony (domyślnie <nazwa>_feedback.html obok wejścia). Typ wykrywany jest z rozszerzenia; w razie potrzeby wymuś --type md|html.

Krok 2: uruchom serwer w tle i otwórz przeglądarkę

Uruchom serwer przez Bash z run_in_background: true. Plik wyjściowy feedback.json umieść obok treści (łatwo go potem znaleźć):

python ~/.claude/skills/feedback-page/scripts/feedback_server.py \
  --page /ścieżka/do/tresci_feedback.html \
  --out /ścieżka/do/feedback.json \
  --open

Serwer wypisze FEEDBACK_URL http://localhost:PORT/ i otworzy przeglądarkę. Powiedz użytkownikowi krótko jak korzystać: zaznacz tekst → "💬 Skomentuj" → wpisz uwagę → na końcu "Wyślij feedback". Zakończ swoją turę - gdy użytkownik kliknie "Wyślij", proces serwera zakończy się i zostaniesz automatycznie wznowiony.

Krok 3: odczytaj feedback i nanieś poprawki do nowej wersji

Po wznowieniu (proces serwera wypisał FEEDBACK_RECEIVED ... i zakończył się) przeczytaj feedback.json:

{
  "source": "tresci.md",
  "created": "2026-...",
  "comments": [
    {"id": 1, "quote": "zaznaczony fragment", "comment": "co zmienić"},
    {"id": 2, "quote": "inny fragment", "comment": "uwaga"}
  ],
  "general": "uwaga ogólna do całości"
}

Każdy quote to dokładny fragment, którego dotyczy comment. general to uwaga do całości.

WAŻNE — DOMYŚLNE WERSJONOWANIE (nie nadpisuj oryginału):

Każda runda feedbacku produkuje nową wersję pliku, oryginał zostaje nietknięty. To pozwala porównywać iteracje, cofnąć się o jedną wersję i mieć czysty audit trail rund poprawek.

Konwencja nazw (auto-bump):

Plik wejściowy	Nowa wersja
scenariusz.md	scenariusz-v2.md (przyjmujemy że bazowy to v1)
scenariusz-v2.md	scenariusz-v3.md
scenariusz-v3.md	scenariusz-v4.md
tresc.html	tresc-v2.html

Procedura:

1. Sprawdź nazwę pliku źródłowego — jeśli kończy się na -vN.<ext>, nowa wersja to -v(N+1).<ext>. Jeśli nie ma sufiksu wersji, nowa to -v2.<ext> (zakładamy że oryginał to v1).
2. Skopiuj plik źródłowy do nowej nazwy, dopiero potem nanieś wszystkie poprawki z feedback.json na kopię. Oryginał zostaje bez zmian.
3. Jeśli plik docelowy już istnieje (np. -v2.md jest już zajęty), bumpuj dalej (-v3.md itd.).
4. Na końcu powiedz krótko użytkownikowi co powstało: scenariusz.md → scenariusz-v2.md (12 zmian).

Nadpisz oryginał TYLKO gdy użytkownik wprost o to poprosi („nadpisz", „bez wersji", „zmodyfikuj plik źródłowy"). W przeciwnym razie zawsze nowa wersja.

Jeśli serwer zakończył się z TIMEOUT albo użytkownik mówi, że użył fallbacku, poszukaj ~/Downloads/feedback.json (lub poproś o wklejenie).

Wskazówki

• Strona jest samodzielna (CSS i JS w środku). Jedyna zależność zewnętrzna to marked.js z CDN w trybie markdown - wymaga internetu do renderowania. Tryb HTML nie potrzebuje CDN.
• Warstwa komentarzy ma prefiks fp- na klasach/id, żeby nie kolidować ze stylami strony. Selekcja jest ograniczona do treści ([data-feedback-root], #fp-content, albo body przy stronach HTML) i pomija własne UI feedbacku.
• Highlight działa też dla zaznaczeń przez wiele elementów. Gdyby gdzieś "nie chwycił" wizualnie, cytat i tak trafia do panelu - feedback nigdy nie przepada.
• Po naniesieniu poprawek warto wygenerować stronę ponownie, żeby użytkownik zrobił kolejną rundę.
• Nie czytaj pliku transkryptu serwera przez shell jeśli działa w tle; czekaj na notyfikację o zakończeniu procesu, a wtedy czytaj feedback.json.