vtube/docs/BOT_WORKFLOW.md

# Bot & goboss workflow — обов'язкові правила

Durable spec для всіх Claude-ботів (gocc1..4) і goboss-планувальника. Project-agnostic.

**Головне правило:** не патчимо "на око". Думай → план → роби. No hardcodes, no patches, SSOT-first, architectural over patches.

## NO MAKE-WORK rule (CRITICAL)

**НЕ давати ботам задачі з пустого в порожнє.** Кожен dispatch має конкретну причину:
- ✅ developer запитав audit / refactor / fix
- ✅ HIGH severity finding з попереднього report потребує follow-up verify
- ✅ нова area не покрита попередніми звітами (concrete gap)
- ✅ regression/test після коміту з реальними змінами

**Не валідні тригери (НЕ робити):**
- ❌ "давай ще раз перевіримо" без нової причини
- ❌ "audit того ж самого через тиждень — раптом щось зміниться"
- ❌ make-work cross-audit / regression / research коли нічого не змінилось
- ❌ дублювання попереднього task'у з той ж scope

Якщо нема валідного тригера — task file = `Чекай.`. Не вигадуй роботу.

## Recommendations cadence (для goboss)

На початку кожної session goboss перевіряє `docs/RECOMMENDATIONS.md`:
- Скільки items OPEN по severity
- Що додано з last session
- Згадай developer-у (1 рядок: `📋 RECOMMENDATIONS: N OPEN (X HIGH, Y MEDIUM, Z LOW). Найпріоритетніше: ...`)
- НЕ виконуй items самостійно — чекай developer-go

---

## Частина A — для goboss (planner)

### A1. Планування перед dispatch

Перед task file для бота goboss МУСИТЬ:

1. **Scope** — one-liner: що зробити, які файли, який контракт.
2. **Якщо multi-step (≥3 discrete steps) АБО architectural** — `Agent(subagent_type: Plan)`. Результат — concrete step-by-step з critical files і trade-offs.
3. **Якщо brainstorming** (невідомий підхід / 2+ competing options) — `superpowers:brainstorming` skill. Записати decision + reasoning у task.
4. **SSOT check** — чи є вже helper/module для цього? Використовуй існуюче.
5. **Recent commits** — `git log --oneline -20` — щоб не дублювати.

### A2. Architectural fixes, not patches

Якщо помилка зустрічається 2+ рази з того ж root cause → REDESIGN, не FIX по одному разу.

`feedback_architectural_not_patches` memory — якщо існує.

### A3. Перевірка cherry-pick'ів

Після cherry-pick bot-зміни:
1. Smoke (`pytest tests/test_<feature>.py -q`)
2. Full regression (`./run_tests.sh` або `pytest -q`)
3. ≥3 commits разом без verify → `gocc2` на drift-check audit
4. Push + verify health endpoint
5. Update `docs/ROADMAP.md` (якщо проект має) у тій самій сесії

### A4. Code review після great IMPL

Після кожного MAJOR step (refactor, new SSOT module, multi-file migration):
1. `Agent(superpowers:code-reviewer)` на результат
2. Передати: commit hash, changed files, task spec link
3. Issue → fix inline АБО queue follow-up PR

---

## Частина B — для ботів (executor)

### B1. Before coding — planning phase

Перед першим code edit:
1. Прочитай task ПОВНІСТЮ.
2. Multi-step (≥3 кроків) АБО scope нечіткий → `Agent(subagent_type: Plan)` з task context. Plan = checklist.
3. Architectural decision → `superpowers:brainstorming` skill. `## Decision` block у report.
4. Unclear → ЗАПИТАЙ goboss (через partial report з `QUESTION:` block). НЕ ВГАДУЙ.

### B2. No hardcodes — SSOT first

Перед кожним новим літералом (path, model name, URL, retry count, language code):
1. `grep -rn "<literal>" config/ lib/`
2. Існує → IMPORT
3. Немає → додай у `config/<domain>.py` як module-level const, потім import

Never:
- `API_KEYS = ['xxx']` у коді (use env)
- `DATA_DIR = '/var/lib/...'` у коді (use config)
- `MAX_RETRIES = 3` у двох файлах (extract до `config.retry`)

### B3. No patches — architectural fixes

Bug знайдено:
1. Root cause (не симптом)
2. Локальний → fix inline + regression test
3. ≥2 місцях АБО ≥2 commits → architectural refactor (SSOT, validator, dedup). НЕ копіюй fix у N місць.

### B4. Test coverage

Кожна нова public function / class / module:
- 1 smoke (happy path)
- 1 edge (empty/invalid/failure)
- 1 integration якщо side effects (DB, HTTP, FS)

Test name: `tests/test_<module>_<feature>.py`. Новий endpoint = новий test.

### B5. Pre-push code review

Після commit, ДО report:
1. Re-read diff (`git diff HEAD~1`)
2. Constraint check проти task spec
3. Large refactor (≥200 LOC АБО ≥5 files): `Agent(superpowers:code-reviewer)` з task spec, diff, own trade-offs.
4. Code-reviewer feedback → fix inline АБО record у report BUGLOG як deferred.

### B6. Report structure

Кожен report МУСИТЬ мати у цьому порядку:
1. **Status** (READY / BLOCKED / FAILED)
2. **Deliverable** (branch, base commit, commit hash, files, LOC delta, tests added)
3. **Scope summary** (3-5 bullets)
4. **Decision notes** (якщо archi — варіант + чому)
5. **Test coverage** (per-module)
6. **Full regression** (pytest tail)
7. **Hardcode self-check** (grep — 0 hits)
8. **BUGLOG** (touched OR deferred)
9. **Deviation** (де відхилився від spec + чому)
10. **Signal** (filename for auto-hook trigger)

---

## Частина C — task file template

```markdown
# Task: <one-line scope>

**Assignee:** gocc<N> (<READ-ONLY AUDIT | IMPL | DECISION>)
**Origin:** <link to prior report / TODO / audit finding>
**Base:** `origin/main` @ `<commit-sha>`

## Workflow requirements (per docs/BOT_WORKFLOW.md)

- **Before coding:** `Plan` agent якщо multi-step; `brainstorming` skill якщо archi
- **SSOT check:** grep existing constants; import not copy
- **After major step:** `Agent(superpowers:code-reviewer)` на commit+diff
- **No patches:** recurring bug = root cause refactor
- **Report:** 10 sections per §B6

<!-- task spec -->
```

---

## Частина D — enforcement + exceptions

### D1. Enforcement

- Report без required sections (§B6) → goboss повертає `MISSING: <sections>`
- Bot patch замість architectural → goboss queue додатковий PR на refactor
- Bot пропустив SSOT, hardcode landed → goboss inline-fix + memory update

### D2. Exceptions (без планів)

Не потрібно planning overhead для:
- Trivial 1-file fix (typo, rename, const update)
- READ-ONLY audit (план = task spec sections)
- Doc-only update
- Emergency rollback (`git revert` — явно)

Bot вважає task — exception → ЗАПИШИ у report `## Planning skipped` з reasoning. goboss review.

### D3. Rollback on violation

Architectural violation post-merge (hardcode landed, patch замість refactor):
1. `git revert <commit>` (not --force, not amend)
2. Dispatch новий PR з proper fix
3. Update `feedback_<violation>.md` memory

---

## Частина E — operational procedures (goboss → bot dispatch)

### E1. Порядок dispatch

1. Запиши task у `~/comms/gocc{N}-task.md` з **унікальним Task ID**.
2. Тригер: `~/bin/trigger-bots gocc{N}` (або `~/bin/trigger-bots` для всіх).

`trigger-bots` робить: clear stale reports → git pull → signal через `~/scripts/trigger_bot.sh` (flock-serialized, paste-buffer + dual-Enter + verify).

### E2. Якщо бот не реагує

- `❯` prompt — Claude процес мертвий
- НЕ Ctrl-C (вбиває Claude)
- Use `~/bin/restart-bots gocc{N}` — kill-session → start-devs → wait 20s → trigger одним скриптом

### E3. Тригер ботів (нова задача)

```bash
~/bin/trigger-bots             # всі gocc1-4
~/bin/trigger-bots gocc2       # один
~/bin/trigger-bots gocc1 gocc3 # subset
```

### E4. Повний перезапуск

```bash
~/bin/restart-bots             # всі: kill+start+wait+trigger
~/bin/restart-bots gocc4       # один
```

⛔ **НІКОЛИ ручний `tmux kill-session`** — використовуй `restart-bots`.

### E5. Task ID правила

- Кожна нова task = новий унікальний Task ID
- Формат: `[goboss YYYY-MM-DD] Task ID: НАЗВА-ЗАДАЧІ`
- Бот порівнює task Task ID vs report Task ID — якщо однакові → "Чекаю.", різні → виконує
- При restart — clear report files перед trigger (restart-bots робить автоматично)

### E6. Context clear policy

`~/bin/clear-bots` (per-bot subset) — використовуй коли:
- Новий епох незалежний від попереднього (different feature/area)
- Контекст ≥30% з 1M (бот сам пише `⚠️ CONTEXT HEAVY` у report)
- Послідовний follow-up на ту саму задачу — НЕ кліри

### E7. Communication scripts (КАНОНІЧНІ)

- `~/scripts/send_to_goboss.sh "<msg>"` — bot → goboss (flock, idle-wait, verify)
- `~/scripts/trigger_bot.sh <session> "<msg>"` — goboss → bot (flock, idle-wait, verify)
- НІКОЛИ raw `tmux send-keys` для quoted text — guard блокує

---

**Reference memories:** `feedback_bot_verification`, `feedback_pre_push_subagent`, `feedback_signal_flood_mutex`, `feedback_simple_no_details`, `reference_bot_comms`.