echo-core/tasks/lessons.md

Lessons Learned

Lecții capturate din corectările lui Marius. Citește acest fișier la începutul oricărei sesiuni de cod (înainte de plan mode) și aplică lecțiile relevante. Iterează neobosit pentru a evita rate drop-uri pe greșeli repetate.

Format per lecție:

## <titlu scurt>
**Data:** YYYY-MM-DD
**Context:** ce făceam când a apărut corectarea
**Greșeala:** ce am făcut greșit
**Regula:** ce să fac în schimb, în viitor
**Când se aplică:** trigger-uri concrete (fișiere, task-uri, situații)

---

Intră în plan mode ÎNAINTE de a executa orice modificare de cod

Data: 2026-05-28 Context: Marius a descris o cerință de îmbunătățire a comenzii /audio cu URL (chunk by chunk). Am implementat direct fără plan mode. Greșeala: Am sărit peste pasul de planificare și am modificat fișierele fără aprobarea lui Marius. Regula: Pentru orice modificare de cod (nu doar task-uri cu 3+ pași), intră în plan mode, prezintă planul, și AȘTEAPTĂ aprobarea înainte de a atinge vreun fișier. Când se aplică: Orice cerere de cod/implementare, indiferent de simplitate aparentă. Dacă e tentant să implementezi direct pentru că pare simplu — e exact momentul să te oprești și să planifici.

Supertonic rejectează ghilimelele curly (Unicode) cu HTTP 500

Data: 2026-05-27 Context: Marius a dat o comandă audio pe Discord cu un URL, iar răspunsul lui Claude conținea „foo" (ghilimele românești curly). Supertonic a returnat HTTP 500: synthesis failed: Found 1 unsupported character(s): ['„'] și răspunsul nu s-a mai auzit. Fără retry logic vizibil în UX — pur și simplu tace. Greșeala: Am presupus că normalize_for_tts produce text deja "TTS-safe" pentru Supertonic. În realitate strip_markdown păstrează ghilimelele Unicode („ U+201E, " U+201D, — U+2014, … U+2026, etc.) pe care Supertonic le refuză. Regula: Înainte de orice apel HTTP la Supertonic, sanitizează punctuația Unicode la echivalentele ASCII („ " " → ", ' ' ‚ → ', – — → -, … → ..., « » → "). Funcția sanitize_punctuation în src/voice/normalize.py face asta și e apelată chiar după strip_markdown în pipeline. Dacă apar caractere noi care crapă Supertonic (ex: simboluri matematice, săgeți), adaugă-le în _TTS_PUNCT_MAP. Când se aplică: Orice cod care trimite text la Supertonic (tools/tts.py, src/voice/tts_stream.py). Inclusiv testare manuală cu curl — folosește text românesc realistic (include „foo", em-dash —, ellipsis …).

Mai multe threads ≠ mai rapid — fitează cpu_threads pe physical cores, nu logical

Data: 2026-05-27 Context: Benchmark tools/voice_bench.py pentru faster-whisper small int8 pe i7-6700T (4 physical / 8 logical cores). Marius a urcat VM-ul de la 2 → 4 → 6 cores online, așteptând că mai multe = mai rapid. Greșeala: Presupoziție implicită că cpu_threads=N scalează liniar cu N. La 6 threads small.p50 a regresat la 2.79s vs 2.25s la 4 threads (+24% MAI LENT). Era ușor de ratat dacă rulam doar un singur pass. Regula: Pentru workload-uri compute-bound (int8/fp16 ML inference, video encode, criptografie) setează cpu_threads = numărul de PHYSICAL cores, NU logical. Hyperthreads adaugă synchronization overhead și memory bandwidth contention fără paralelism real. Sweet spot tipic: min(num_physical_cores, $optimal_threads). Verifică cu lscpu (Core(s) per socket × Socket(s) = physical; CPU(s) = logical). Dacă faci benchmark, rulează SWEEP nu single point — 2/4/6/8 threads să vezi unde e curba reală. Când se aplică: Configurare cpu_threads, OMP_NUM_THREADS, MKL_NUM_THREADS, torch.set_num_threads(), ffmpeg -threads, sau orice runtime ML/inference. Mai ales pe Proxmox VM-uri unde "more cores online" sună ca îmbunătățire. Întreabă-te: e workload compute-bound (yes → physical only) sau IO-bound (yes → logical OK)?

Nu șterge crontab-uri din sistem fără confirmare explicită

Data: 2026-05-20 Context: Marius a cerut să șteargă "newsletter test din cron jobs". Am interpretat că check_newsletter_cercetasi.py din crontab de sistem face parte din "newsletter test". Greșeala: Am inclus în scop un crontab de sistem care nu fusese menționat explicit. "newsletter test" se referea doar la job-ul newsletter-test din cron/jobs.json. Regula: Crontab-ul de sistem (crontab -l) este separat de cron/jobs.json. Nu îl modifica fără instrucțiuni explicite. Dacă scope-ul nu e clar, întreabă înainte de a acționa pe crontab sistem. Când se aplică: Orice task care implică ștergerea sau modificarea cron jobs — distinge întotdeauna între cron/jobs.json (APScheduler) și crontab-ul de sistem.

Nu scrie manual în index.json — rulează update_notes_index.py

Data: 2026-04-29 Context: Salvam o notiță din Facebook reel în memory/kb/. Am adăugat manual o intrare în index.json cu schema greșită (id + path în loc de file), ceea ce a blocat notes.html pe "Se încarcă..." cu un TypeError în renderNoteCard. Greșeala: Am editat index.json direct, cu o schemă diferită față de ce produce update_notes_index.py. Regula: Niciodată nu scriei manual în memory/kb/index.json. Fluxul corect: (1) creezi fișierul .md în memory/kb/<categorie>/, (2) rulezi python3 tools/update_notes_index.py. Dacă ai nevoie să salvezi o notiță din Facebook/video, folosești scripts/transcribe_video.sh <URL> <lang> --save-kb care face totul corect. Când se aplică: Orice salvare de notiță în KB (Facebook, YouTube, coaching, insights, orice). Dacă ești tentat să json.dump în index.json — stop, rulează scriptul.

Verifică că modelul/tool-ul numit chiar are capabilitatea ÎNAINTE de a planifica în jurul lui

Data: 2026-06-27 Context: Marius a cerut să folosesc gemma4:31b-cloud (Ollama) pentru decodare audio ca alternativă la Whisper. Am verificat pe pagina oficială Ollama: variantele cloud (31b) suportă doar Text+Image — audio există DOAR pe E2B/E4B (edge, local), iar acela e stricat de o regresie upstream deschisă (issue #16584). Premisa cererii era infezabilă. Greșeala (evitată): Dacă planificam direct integrarea fără să verific pagina modelului, scriam cod de cablare Ollama audio care n-ar fi funcționat niciodată. Search-ul generic spunea „Gemma 4 are audio" — adevărat la nivel de familie, fals pentru modelul cloud specific cerut. Regula: Când userul numește un model/serviciu specific pentru o capabilitate (audio, vision, tool-use, context lung), verifică pagina/docs ACELUI model exact înainte de a planifica. Capabilitățile diferă per variantă (cloud vs edge, sizes). Fetch pagina oficială, nu te baza pe search agregat la nivel de familie. Când se aplică: Orice task care pornește de la „folosește modelul X pentru Y". Confirmă X→Y pe sursa primară înainte de plan mode.

Corecția post-STT de text e cosmetică dacă consumatorul e un LLM — fixează la sursă (model), nu cu dicționar

Data: 2026-06-27 Context: Plan inițial pentru curățarea transcrierii Whisper avea 4 piese, inclusiv dicționar de restaurare diacritice + canonicalizare wake-word. Două review-uri independente (/autoplan CEO+Eng) au arătat: textul transcris merge la Claude, care citește română fără diacritice perfect; NU există wake-word gate în cod (on_segment_done dispatch necondiționat); singurul consumator precis (detect_voice_change) e deja fuzz-hardenat. Un spike a confirmat că modelul RO-finetuned (mikr/whisper-small-ro-cv11) înjumătățește WER (24%→10%) și fixează numerele la SURSĂ, +0.33s latență. Greșeala (evitată): Construirea unui strat de corecție hand-curat (întreținere perpetuă, risc de regresie pe cuvinte ambigue) când fix-ul real era un model finetuned cu același cost de inferență. Regula: Înainte de a peticit output-ul unui model ML cu post-procesare rule-based, întreabă: (1) cine e CONSUMATORUL textului? (un LLM tolerează erori; un parser regex nu); (2) există un model finetuned care fixează la sursă cu același cost? Spike-uiește modelul ÎNAINTE de a scrie straturi de corecție. Verifică unde merge output-ul prin cod, nu presupune un gate care „pare" că există. Când se aplică: Orice îmbunătățire de calitate STT/OCR/ML output. Tool de spike: tools/voice_stt_spike.py.