Update AGENTS.md and SKILL.md files to clarify task handling and bug reporting. Added documentation for bug-related tasks in AGENTS.md and refined descriptions in phase-work and side-work skills to specify their usage and differentiate from bug work.

2026-08-20 09:06:59 +03:00
parent ac17abfd90
commit e18a09ea82
6 changed files with 117 additions and 7 deletions
@@ -0,0 +1,91 @@
 ---
 name: bug-work
 description: >-
  Принимает баг в уже сделанном, при необходимости обсуждает путь и чинит.
  Файлы в docs/bugs/, индекс отдельно от фаз. Используй при «баг», «почини»,
  «регрессия», «сломалось», «fix the bug», «возьми баг N». Не для новой фичи
  (/side-work), фазы среза (/phase-work) и ревью (/phase-review).
 ---
 # Баги
 Это не фаза и не срез. Сломалось то, что уже должно работать: принять, при
 нужде согласовать путь, починить. Документы — `docs/bugs/`, индекс —
 `docs/bugs/README.md`. В `docs/phases/` и «Вне очереди» не класть.
 Один запуск — **один баг**. Код до записи в индекс не писать.
 ## Когда это, а когда нет
 Прочитай `docs/bugs/README.md`, `docs/phases/README.md` и инварианты в
 `AGENTS.md`.
 - Уже стоит ⬜/🔄 в индексе багов — бери его, не заводи второй.
 - Это ещё не сделанная фаза в `docs/phases/` — скажи и отдай `/phase-work`.
 - Новая фича, склейка систем, DX — `/side-work`.
 - Ревью среза — `/phase-review`.
 Номер передали (`/bug-work 3`) — берёшь его. Нет — первая ⬜ в индексе, у
 которой нет ветки `bug/<N>-*`. Нет свободных и пользователь только что описал
 симптом — заводи новый.
 ## 1. Принять
 Записать симптом так, чтобы следующий агент его узнал без этого чата: что
 видит игрок / падающий тест / лог; чего ждали; как воспроизвести, если путь
 не в одну строку.
 Пользователь предложил фикс — проверь, что это причина, а не симптом. Лучший
 путь рядом — назови его, не чини молча худший.
 ## 2. Обсудить, когда нужно
 Путь один и не трогает протокол, сейв и инвариант — чинить, не спрашивать.
 Два+ разумных пути **или** правка протокола / сейва / инварианта — два–три
 варианта и **рекомендация**. Стоп, пока не сказали «ок», «делай», «как
 рекомендуешь». Молчание — нет. Соседнее «заодно» в отчёт, не в объём.
 ## 3. Документ
 `docs/bugs/<NN>-<slug>.md` и строка в индексе. Номер: максимум по папке и
 индексу, плюс один, затем `git branch --list "bug/<N>-*"`. Занято — следующий.
 Гонку ловят ветки, не индекс: у нового бага на `main` строки ещё нет.
 Каркас короче фазы, не копия:
 - **Симптом** — что сломано и как увидеть
 - **Причина** — когда известна; иначе «ищу» и дописать тем же коммитом, что код
 - **Путь** — выбранный фикс; отвергнутые — одной строкой, если обсуждали
 - **Задачи** — чеклист
 - **Тест, без которого не закрыт** — обычно один, по Testing policy в `AGENTS.md`
 - **Стоп** — чего не трогать
 Дизайн-док не писать. «Было / Стало» не нужно: это регрессия, не решение.
 Индекс — новая строка, статус 🔄, если сразу чинишь; ⬜, если просили только
 записать. Просил только документ — здесь конец.
 ## 4. Работа
 Заявка `git branch bug/<N>-<slug>` **до** кода. Новые файлы и 🔄 живут на этой
 ветке.
 Дальше — как [phase-work](../phase-work/SKILL.md), с отличиями:
 - префикс ветки `bug/`, не `phase/`; индекс — `docs/bugs/README.md`;
 - worktree обязателен, только если основное дерево грязное или рядом идёт
  другая ветка. Чистое `main` — можно в этом дереве;
 - шаблон фазы не заполнять. Тест из файла бага — да, «Критерий готовности»
  фазы — нет;
 - ✅ в индексе — последним коммитом ветки, в нём только строка статуса.
 Слияние и замок `merge/lock` — как у `/phase-work`. Не пушь.
 Не смог закрыть тест — оставь ⬜ и напиши почему. Полработы с честной пометкой
 лучше, чем ✅ с дырой.
 ## Отчёт
 Симптом одной строкой; путь, если выбирали; баг и ветка; какой тест добавлен;
 что прогнал; что осталось ⬜; слита ли ветка в `main`.
@@ -1,6 +1,6 @@
 ---
 name: phase-work
-description: Берёт ровно одну фазу из среза в docs/phases/ и доводит её до конца — в своём git worktree и на своей ветке, чтобы над одним срезом можно было запустить несколько агентов параллельно. Используй, когда просят «сделай фазу 25», «возьми фазу», «реализуй фазу», «начни срез», «раздели срез между агентами», «work on the phase». Не для ревью уже написанного — там /phase-review, и не для правки одного файла по просьбе.
+description: Берёт ровно одну фазу из среза в docs/phases/ и доводит её до конца — в своём git worktree и на своей ветке, чтобы над одним срезом можно было запустить несколько агентов параллельно. Используй, когда просят «сделай фазу 25», «возьми фазу», «реализуй фазу», «начни срез», «раздели срез между агентами», «work on the phase». Не для ревью уже написанного — там /phase-review, не для бага — /bug-work, и не для правки одного файла по просьбе.
 ---
 # Работа над фазой
@@ -3,8 +3,8 @@ name: side-work
 description: >-
  Обсуждает задачу вне запланированных срезов, пишет под неё фазы и делает на
  отдельной ветке. Используй при «сделай отдельно», «вне среза», «отдельная
-  задача», «не из фаз», «side-work», «обсуди и сделай». Не для «сделай фазу N»
+  задача», «не из фаз», «side-work», «обсуди и сделай». Не для бага
-  (/phase-work) и не для ревью (/phase-review).
+  (/bug-work), «сделай фазу N» (/phase-work) и ревью (/phase-review).
 ---
 # Отдельная задача вне среза
@@ -18,8 +18,9 @@ description: >-
 ## 1. Обсуждение
-Прочитай `docs/phases/README.md`, инварианты в `AGENTS.md` и затронутые
+Прочитай `docs/phases/README.md`, `docs/bugs/README.md`, инварианты в
-дизайн-доки. Это уже чья-то фаза в индексе — скажи и отдай `/phase-work`.
+`AGENTS.md` и затронутые дизайн-доки. Это уже чья-то фаза в индексе — скажи
 и отдай `/phase-work`. Регрессия уже сделанного — `/bug-work`.
 Два–пять вопросов, два–три варианта, **рекомендация обязательна**. Спросить
 только форму: что увидит игрок; протокол / HTTP / сейв; какой инвариант; одна
@@ -30,7 +31,9 @@ description: >-
 ## 2. Куда класть
-**Мелкое** (баг, дырка, одна кнопка) — фаза в секции **«Вне очереди»** в конце
+**Баг / регрессия** — не этот скилл, [bug-work](../bug-work/SKILL.md).
 **Мелкое** (дырка, одна кнопка, DX) — фаза в секции **«Вне очереди»** в конце
 индекса. Это срез без номера, чтобы не спорить со срезом 10. Дизайн — `##` в
 `docs/design/off-queue.md`; файла нет — заведи с заголовком, зачем он.
@@ -25,6 +25,7 @@ way; this file is *how to work in them*.
 | clock speed buttons and high-speed stride | `src/HSchool.Simulation/ClockSpeed.cs` **and** [`docs/design/session.md`](docs/design/session.md) — phase 40 |
 | talks, opinions, fights, romance pack | [`docs/design/social.md`](docs/design/social.md) — slice 9, phases 41–47 |
 | lesson consequences (teacher present, skill, warmth, textbook, weather commute) | [`docs/design/off-queue.md`](docs/design/off-queue.md) — phases 48, 50–53 |
 | a bug in already-shipped behaviour | `.claude/skills/bug-work` — document in `docs/bugs/`, discuss only if the fix has a fork, then patch |
 | a task that is not in any slice | `.claude/skills/side-work` — discuss, document in «Вне очереди» or a new named slice, then implement |
 ## Commands
@@ -0,0 +1,13 @@
 # Баги
 Индекс регрессий в уже сделанном. Статус: ⬜ не начат, 🔄 в работе, ✅ готов.
 Это не фазы: номера не спорят со срезами, в `docs/phases/` не дублировать.
 Новая фича и склейка систем — [«Вне очереди»](../phases/README.md#вне-очереди)
 или отдельный срез, скилл `/side-work`. Как работать с багом —
 [`.claude/skills/bug-work`](../../.claude/skills/bug-work/SKILL.md).
 | Баг | Статус | Симптом |
 | --- | --- | --- |
 Пока пусто. Первую строку пишет `/bug-work`.
@@ -2,6 +2,8 @@
 Индекс. Статус: ⬜ не начата, 🔄 в работе, ✅ готова.
 Регрессии уже сделанного — [`../bugs/README.md`](../bugs/README.md), не сюда.
 ## Срез 1. Оболочка и карта
 Дизайн закрыт: [`../design/near-term.md`](../design/near-term.md),
@@ -229,7 +231,7 @@
 Склейка уже живых систем и мелкий DX, не новый кусок игры. Номера не спорят со срезом 10.
 После каждой игровой фазы школа целая. 50–52 стоят на 48; 53 — на 18 и 32, можно параллельно
-с 48. 49 от них не зависит.
+с 48. 49 от них не зависит. Баг в уже сделанном — [`../bugs/README.md`](../bugs/README.md).
 | Фаза | Статус | Зачем |
 | --- | --- | --- |