lessons-update

Lessons Update — wspólny skill nauki

Cel: po każdym non-trivial task wyciągnąć to czego się nauczyliśmy i zachować jako persistent memory, żeby kolejne sesje nie powtarzały tych samych błędów. Memory ładuje się przez SessionStart hook (project-scoped), więc każda zapisana lekcja zwiększa baseline competence wszystkich przyszłych sesji.

Kiedy uruchamiać

Triggery proaktywne (sam to wywołaj, nie czekaj):

• Po gh pr merge / commit zakończonym
• Po fazie audytu (Faza 1/3/4/5/...)
• Po multi-file change (≥3 pliki) lub multi-step task
• Po wykryciu fix-induced regression (najgorszy signal — fix wprowadził nowy bug)
• Po backtracking (musiałeś cofnąć decyzję)
• Po surprise (kod zachowywał się inaczej niż zakładałeś)

Skip rules:

• Trivial reads (sprawdzanie statusu, ls, grep do informacji)
• Pure refactors bez napotkania błędów
• Documentation updates
• Akcje które tylko klikają w UI / ustawiają flagi
• Powtarzanie znanego procesu bez nowych wniosków

Jawny trigger od usera: /lessons-update lub "zaktualizuj lessons" / "co się nauczyliśmy?".

Workflow

Krok 1: Recap

Streszcz w 1-3 zdaniach co właśnie zostało zrobione. To context dla decyzji "warto / nie warto".

Krok 2: Reflection — 5 pytań

Przejdź po sesji i odpowiedz uczciwie. Każde "tak" = kandydat na lesson:

1. Czy coś się nie udało lub zaskoczyło? (TS error po commit, edge case który zignorowałem, fail w MCP call)
2. Czy musiałem backtrack'ować lub fix'ować fix? ⚠️ Najwyższy signal — fix-induced regressions.
3. Czy coś założyłem co się okazało nieprawdą? (np. "bonus_analyses jest w migracjach", "invokeEdge zwraca FunctionsHttpError shape")
4. Czy widzę pattern który może się powtórzyć? (np. "subagent zaraportował clean ale nie sprawdził callerów")
5. Co bym chciał wiedzieć upfront następnym razem?

Krok 3: Detect duplicates

Dla każdego kandydata, najpierw sprawdź czy już istnieje lesson w memory/:

# Prefer repo memory/ (walk up looking for memory/MEMORY.md — canonical
# location used by gamedev-toolkit-claude auto-load hook).
PROJ_MEM=""
CUR="$(pwd)"
for _ in 1 2 3 4 5 6 7 8 9 10 11 12; do
  if [ -f "$CUR/memory/MEMORY.md" ]; then
    PROJ_MEM="$CUR/memory"
    break
  fi
  [ "$CUR" = "/" ] && break
  CUR="$(dirname "$CUR")"
done

# Search by keyword from candidate
grep -li "<keyword>" "$PROJ_MEM"/lesson_*.md

Jeśli istnieje pasująca lekcja:

• Update path (krok 5) — append nowy case do istniejącej
• NIE twórz duplikatu

Jeśli nie istnieje:

• Create path (krok 4) — nowa lekcja

Krok 4: Create new lesson

Filename convention: lesson_<short_topic>.md (lub feedback_* jeśli to feedback procesowy, nie technical anti-pattern).

Template:

---
name: <short title — pasuje do MEMORY.md one-linera>
description: <jednozdaniowy trigger phrase — keyword który mam zobaczyć w przyszłym kodzie>
type: lesson | feedback
---

**Reguła**: <jednozdaniowa zasada do zapamiętania>

**Why**:
<konkretny case z sesji — co się stało, dlaczego, jaki był koszt (wasted hours, regresja, security gap, RODO leak). MUSI być specyficzny: file:line, error message, exact symptom. Bez "uważaj na bugi".>

**How to apply**:
- <konkretny check do wykonania w przyszłości — bullet point>
- <grep / pattern / file path do sprawdzania>
- <link do related lesson jeśli pasuje>

**Occurrences**:
- <data> — <session ID jeśli masz, inaczej krótki opis>: <co się stało>

Krok 5: Update existing lesson

Jeśli pattern się powtórzył, dopisz nowy occurrence do istniejącej lekcji:

**Occurrences**:
- 2026-04-25 — original case: <opis>
- 2026-05-02 — <new case>: <co się stało, czemu pattern się powtórzył mimo lekcji>

Plus jeśli reflection ujawnia nową fasetę patternu której wcześniej nie było:

• Dopisz do How to apply nowy bullet
• Update Reguła jeśli się rozjeżdża (rzadko — większość patternów jest stała)

Krok 6: ALWAYS-CONFIRM gate

Zanim zapiszesz, pokaż userowi:

Proponuję [nową lekcję | update lesson_X]:

═══════════════════════════════════
<draft content>
═══════════════════════════════════

Decyzja:
- ok / save → zapisuję
- skip / nie warto → pomijam
- change <co zmienić> → poprawiam

User decyduje. NIE zapisuj automatycznie.

Krok 7: MEMORY.md index update (jeśli nowa lekcja)

Po zapisie nowej lekcji:

1. Read MEMORY.md
2. Dodaj one-liner w odpowiedniej sekcji (Lessons / Process / Project)
3. Format: - [<title>](<file>.md) — <hook keyword + jednozdaniowa esencja>
4. Optymalizuj pod recognition — keyword który mam zobaczyć w kodzie aby skojarzyć z lekcją

Limity: MEMORY.md ≤ 200 linii / ≤ 10KB. Jeśli przekracza, zaproponuj /anthropic-skills:consolidate-memory.

Krok 8: Confirm save + close

Po zapisie potwierdź userowi:

✅ Saved: <path>
Index updated: <one-liner added/refreshed>
Active in next session via SessionStart hook (~/.claude/hooks/auto-load-lessons-kmr.sh).

Heuristyki jakości lekcji

DOBRA lekcja:

• Specyficzna: file:line, error code, exact pattern
• Trigger-friendly: keyword w opisie który ja zobaczę w przyszłym kodzie
• Actionable: "How to apply" ma checks/greps/triggers, nie ogólne rady
• Bounded: jedna lekcja = jeden pattern (nie kombo 3 niezwiązanych)

ZŁA lekcja (nie zapisuj):

• "Uważaj na bugi" / "Pisz dobre testy"
• Restating dokumentacji frameworka (znajdę w docs)
• Trivia o jednym pliku które nie powtarza się (use comment in code, not memory)
• Duplikaty istniejących lekcji bez nowego signal

Self-check przed wywołaniem

Zanim invoke'uję ten skill, zadaj sobie:

• Czy jest cokolwiek z 5 pytań reflection do zachowania? Jeśli wszystkie nie → skip skill, NIE wywołuj.
• Jeśli jest 1+ kandydat → invoke i przejdź workflow.

Integracja z innymi skillami

• full-audit v2: na końcu każdej fazy audytu (Faza 1/3/4/5/...) explicit wskazuje "now invoke lessons-update". Dodaj sentence do report sekcji "PLAN NAPRAWY" w full-audit.
• anthropic-skills:consolidate-memory: gdy MEMORY.md > 200 linii, ten skill prosi o uruchomienie consolidate-memory zamiast dalej dorzucać.
• session-summary: na koniec sesji może wywołać lessons-update jako ostatni step.

Auto-detect project

Hook ładuje lessons na podstawie cwd. Ten skill MUSI zapisywać do tego samego folderu memory:

# Project memory lives at <repo>/memory/. Auto-load hook walks up from cwd
# looking for memory/MEMORY.md — this skill should write to that same dir.
PROJ_MEM=""
CUR="$(pwd)"
for _ in 1 2 3 4 5 6 7 8 9 10 11 12; do
  if [ -f "$CUR/memory/MEMORY.md" ]; then
    PROJ_MEM="$CUR/memory"
    break
  fi
  [ "$CUR" = "/" ] && break
  CUR="$(dirname "$CUR")"
done

For brand-new projects without memory/ yet: mkdir -p memory && touch memory/MEMORY.md plus seed a minimal index header. The unity-claude-template repo ships this skeleton.

Output do user (final summary)

Po skończonym workflow, podsumuj:

Lessons review:
- Reflected on N kandydatów
- Saved: M nowych / K updated existing
- Skipped: J (reasons listed)

MEMORY.md: <linecount> linii (limit 200), <KB>KB

Co poszło najlepiej w tej sesji: <jedna fraza>
Co najbardziej kosztowało: <jedna fraza>

To zamyka pętlę nauki — user widzi jakie lekcje wpadły do długoterminowej pamięci.