feedback-page

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.

1. 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).

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):

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).

1. Skopiuj plik źródłowy do nowej nazwy, dopiero potem nanieś wszystkie poprawki z feedback.json

na kopię. Oryginał zostaje bez zmian.

1. Jeśli plik docelowy już istnieje (np. -v2.md jest już zajęty), bumpuj dalej (-v3.md itd.).
2. 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.