vtube/docs/REFACTOR_RULES.md

Refactor / Cleanup / Bug-fix / Feature — definitions

Чотири типи змін. Кожна задача має ідентифікувати свій тип. Це визначає:

• Тригер (хто запитує: developer / audit / автоматичний)
• Scope (skill rough effort)
• Тестування (regression / smoke / нове)
• Як комітити (commit message prefix)

---

REFACTOR

Що це: зміна структури коду без зміни поведінки. Goal — clearer code, less duplication, easier maintenance.

Не змінює:

• HTTP responses (statuses, JSON shape, HTML output byte-for-byte для existing inputs)
• DB schema (без migration)
• API contracts
• Visual rendering for users

Приклади у tubev:

• Винести modules/video.etlua у shared partial з per-site theme overrides → 14 сайтів дають однаковий HTML output, але код DRY (відсутнє ~60% дублювання)
• Розбити 8081/views/layout.etlua 1223L монолітом на partials аналогічно іншим 13 сайтам → той же rendered HTML, чистіша структура
• Уніфікувати sync.sh на rsync-парадигму (7 selective → 7 rsync) → той же файловий результат, єдина mental model

Тестування:

• Regression smoke — той же rendered HTML before/after на тестовому сайті
• Diff snapshot — curl <before> vs curl <after> має бути identical
• Якщо diff — це BUG у refactor, треба фіксити

Комміт: refactor: <scope>: <change>

Хто запитує: developer (go: refactor X). НІКОЛИ боти/goboss самостійно — тільки коли явна директива.

---

CLEANUP

Що це: видалення dead code / dead files які точно не використовуються.

Не змінює:

• Нічого, бо видаляється тільки те що було не задіяне.

Приклади у tubev:

• Видалити DEL_*.etlua (24 файли × 6 сайтів) — префікс DEL_ явно signals tombstone
• Видалити *copy*.etlua, *_bak*.etlua, *_old/ папки — backup-via-rename артефакти
• Видалити _test.etlua, .test.js з prod tree — tests не у prod
• Видалити legacy UA-* GA snippets (Universal Analytics EOL 2023-07)

Verification перед видаленням:

• grep -rn "<filename>" backup_<port>/ — чи десь reference?
• Якщо posicionado — re-classify як refactor (треба міняти reference спершу)
• Якщо unreferenced — safe to delete

Тестування:

• Sync.sh re-run → backup ідентичний прод (для rsync mirror sites)
• Smoke render головних сторінок — нічого не зламалось

Комміт: cleanup: <scope>: remove <what>

Хто запитує: developer ("видали DEL_*"). Боти знаходять і рекомендують у RECOMMENDATIONS.md, але не видаляють самі без явного go.

---

BUG-FIX

Що це: код неправильно працює, треба виправити.

Змінює поведінку — навмисно, бо поведінка була некоректна.

Приклади у tubev:

• 8112 має 2 GA properties у одному gtag — likely баг (gtag config записує на дві property)
• 8085 submodule views/static/js/lib drift — modified reference але не committed; treba decide rollback або commit
• Site domain hardcoded у CSP <meta> — правильніше через nginx HTTP header
• header copy bogolink 25_10_22.etlua (8112) — typo в назві файлу = drift від 4 інших сайтів

Тестування:

• Reproducer test (показує проблему)
• Fix test (показує що пофіксено)
• Regression — нічого іншого не зламалось

Комміт: fix: <scope>: <symptom> → <root cause>

Хто запитує: будь-хто (developer, audit, користувач). Bots HIGH severity findings → goboss flagує developer-у.

---

FEATURE

Що це: нова поведінка яка раніше не була доступна.

Приклади у tubev:

• Винести views/config/site.lua (новий конфіг файл) → нова можливість централізованого управління site_domain / GA ID / CDN host
• SRI integrity для third-party scripts → нова security guarantee
• Build-step для 8148 (винести з sync.sh) → нова функція автоматизації

Тестування:

• New tests для нової поведінки (smoke + edge + integration)
• Regression — нічого не зламалось

Комміт: feat: <scope>: <new behavior>

Хто запитує: developer / product. Боти не пропонують features самостійно.

---

Як вибирати

Зміна	Type
"Винести в shared module / extract / DRY-it"	REFACTOR
"Видали мертве" / "забрати DEL_*" / "wipe legacy"	CLEANUP
"Не працює як треба" / "неправильна відповідь" / "конфлікт даних"	BUG-FIX
"Додай нове" / "тепер можна X" / "нова кнопка/endpoint"	FEATURE

Якщо змішується — розбий на окремі коміти, по одному типу на commit. Mixed commits ламають revert / cherry-pick.

---

Recommendations vs Plans (важливо)

Recommendation = "ось що варто зробити, ось чому, ось приблизний effort". Plan = "ми зараз робимо наступне: ...".

Боти створюють recommendations у RECOMMENDATIONS.md. Plans створюються тільки коли developer каже "зробити".

goboss не виконує recommendations самостійно. Тільки нагадує developer-у періодично через session-start summary поки developer не скаже "роби X" або "видали X з backlog".