Imported from lfuuu/claude-rules (shared-skills/process/backlog/SKILL.md). Install upstream with npx skills add lfuuu/claude-rules --skill backlog. Copyright stays with the author.

Backlog: журнал технического долга

Фиксирует осознанные технические компромиссы, отложенные задачи, известные ограничения в docs/backlog/NNN-<slug>.md. Жизненный цикл: open → in-progress → done (или open → wontfix).

Отличие от /todo

Когда что: если идея не реализована и нужен drill -- /todo. Если в коде/архитектуре уже принят компромисс и нужно зафиксировать чтобы не забыть -- /backlog.

Автономность

Критерий завершения

Не возвращай управление, пока выполнено одно из:

• запись создана/обновлена и зафиксирована в файле;
• наступила блокирующая ошибка из § «Блокирующие ошибки».

Промежуточные шаги -- НЕ точки выхода. Промежуточные summary, "продолжить?", "следующий шаг?" -- запрещены до финального отчёта.

Политика разрешения неопределённости

При развилке -- НЕ спрашивай. Применяй правила в порядке сверху вниз:

1. Если поле frontmatter неоднозначно (priority, category) -- бери разумное значение по контексту вызова.
2. Если slug коллизирует -- добавь суффикс -2, -3.
3. Если файла или директории нет -- создай (docs/backlog/).

Блокирующие ошибки (исчерпывающий список)

Останавливаться можно ТОЛЬКО при:

• неоднозначность scope: непонятно, это done или wontfix (требуется решение Архитектора);
• запрос на коммит / push (правило CLAUDE.md: одно разрешение -- один коммит).

Контракт возврата

Возвращайся к оркестратору ТОЛЬКО с финальным результатом всей задачи. Промежуточные вопросы запрещены.

Входные данные

Аргумент: $ARGUMENTS -- подкоманда и параметры. Без аргумента -- спросить у пользователя.

Подкоманды

add <описание> (основная команда для агентов)

Создаёт запись о техническом долге.

Алгоритм:

1. Вычислить следующий номер NNN:

   ls docs/backlog/ 2>/dev/null | grep -oE '^[0-9]{3}' | sort -n | tail -1

   Если пусто -- 001. Иначе $((max + 1)) с zero-padding до 3 знаков.

2. Сгенерировать slug из первых значимых слов (правила транслитерации из /todo):

   • Транслитерация кириллицы (а→a, б→b, в→v, г→g, д→d, е→e, ё→e, ж→zh, з→z, и→i, й→i, к→k, л→l, м→m, н→n, о→o, п→p, р→r, с→s, т→t, у→u, ф→f, х→h, ц→ts, ч→ch, ш→sh, щ→sch, ъ→, ы→y, ь→, э→e, ю→iu, я→ia).
   • Нижний регистр, пробелы → дефис, выбросить стоп-слова (в, на, и, по, для, c, из), 3-5 слов, до 50 символов.

3. Определить category по контексту описания:

   • limitation -- известное ограничение реализации (нет SA-lookup, нет multi-select в API, etc.).
   • optimization -- известное место для performance-улучшения.
   • refactor -- запланированный рефакторинг (вынести модуль, переименовать).
   • ux -- UX-улучшение, не вошедшее в MVP.
   • security -- security-TODO.
   • ops -- эксплуатационная задача (мониторинг, бэкапы, runbook).
   • Если контекст неясен -- limitation.

4. Определить priority по контексту:

   • high -- блокирует другую работу или есть user-impact.
   • medium -- по умолчанию.
   • low -- косметика, оптимизация без острой необходимости.

5. Определить source:

   • Если описание содержит ссылку на todo-NNN -- source: todo-NNN.
   • Если вызов от агента (по контексту) -- source: <agent-name> (backend / frontend / reviewer / teamlead).
   • Иначе -- source: manual.

6. Создать файл docs/backlog/NNN-<slug>.md:

   ---
   title: "<человеко-читаемый заголовок>"
   status: open
   category: <limitation | optimization | refactor | ux | security | ops>
   priority: <low | medium | high>
   source: <todo-NNN | review-NNN | <agent> | manual>
   created: <YYYY-MM-DD>
   last-updated: <YYYY-MM-DD>
   ---
   
   # <заголовок>
   
   ## Контекст
   
   <откуда взялась задача: ссылка на todo-NNN, ревью-finding, файл/строка кода, runbook>.
   
   ## Описание
   
   <что именно нужно сделать>.
   
   ## Зачем
   
   <технический/бизнес-мотиватор: почему это не "мусор", а реальный долг>.
   
   ## Acceptance criteria
   
   - <измеримый критерий 1>
   - <измеримый критерий 2>
   
   ## Влияние
   
   <что блокирует / какой риск, если не сделать>.

7. Сообщить: имя файла, NNN, category, priority, ссылка для /backlog show NNN.

list [filter]

Показать таблицу всех записей docs/backlog/NNN-*.md. Опциональный фильтр:

• open -- только status=open
• in-progress -- только in-progress
• category=<cat> -- по категории
• priority=high -- по приоритету

| NNN | title | status | category | priority | source | last-updated |
|-----|-------|--------|----------|----------|--------|--------------|
| 001 | ... | open | limitation | medium | todo-029 | 2026-05-21 |
| 002 | ... | in-progress | refactor | low | reviewer | 2026-05-22 |

Данные читать из frontmatter каждого файла.

start <NNN>

Перевести status: open → status: in-progress. Обновить last-updated. Используется, когда работа начата (опциональный шаг -- агенты могут пропустить и сразу done).

done <NNN> [ссылка]

1. Дописать в секцию ## Реализация (создать, если нет):

   ## Реализация
   
   - <дата YYYY-MM-DD>: <ссылка или описание>

2. Перевести status на done. Обновить last-updated.

3. Сообщить: «Запись NNN закрыта».

wontfix <NNN> <причина>

1. Дописать в секцию ## Решения (создать, если нет):

   ## Решения
   
   - <дата>: wontfix -- <причина>

2. Перевести status на wontfix. Обновить last-updated.

show <NNN>

Прочитать файл docs/backlog/NNN-<slug>.md и вывести содержимое.

Без аргументов

Спросить у пользователя: «Что зафиксировать в backlog? (тех.долг, ограничение, отложенный scope)». Получить описание, выполнить add <описание>.

Жизненный цикл

open         -- зафиксирован долг
  ↓ /backlog start NNN  (опционально, при начале работы)
in-progress  -- работа идёт
  ↓ /backlog done NNN [ссылка]
done         -- реализовано

  ↓ /backlog wontfix NNN <причина>  (из любого состояния)
wontfix      -- решено не делать

Правила использования агентами

Этот skill используется агентами автоматически (без вмешательства Архитектора):

1. /backend, /frontend, /devops -- если по ходу реализации:

   • оставлен TODO/FIXME в коде с понятной семантикой;
   • принят технический компромисс (заглушка, неполная реализация, отложенный edge-case);
   • намеренно урезан scope (не вошло в текущую задачу, но известно что нужно).

   Действие: /backlog add <краткое описание + ссылка на файл/строку>. После записи продолжить основную работу.

2. /reviewer -- если в ревью обнаружен tech-debt-finding, который НЕ блокирует merge (NOTE-уровень), но требует фиксации:

   • /backlog add <описание + ссылка на код> с source: reviewer.

3. /teamlead -- если при планировании многофазного todo выделен deferred-scope (что-то в будущих фазах или backlog'е):

   • /backlog add <описание + ссылка на todo-NNN> для каждого пункта deferred-scope.

4. /techwriter -- если в документации обнаружен пробел, который нельзя закрыть в текущей задаче:

   • /backlog add <описание + ссылка на doc> с source: techwriter.

Границы

• Управляет только docs/backlog/ -- никакой бизнес-логики.
• НЕ замена issue-tracker -- локальный scratchpad для тех.долга, видимый в репо.
• НЕ замена /todo -- /todo это идеи в инкубаторе, /backlog это известный долг.
• Коммит добавленных записей -- по общим правилам CLAUDE.md, не автоматически (для agent-вызовов запись делается в той же ветке, что и основная работа, попадает в общий коммит).

Типичный поток

Из реализации (агент)

/backend завершил Phase 4 todo-029. В QuotaVersionsTable реализован
fallback "sa: UUID-8" для service_account, полнокровный SA-lookup отложен.
→ /backlog add SA-lookup для actor_id в QuotaVersionsTable -- сейчас fallback "sa: UUID-8", полнокровный резолв display_name через service-accounts API отложен (todo-029 Phase 4)
   → создан docs/backlog/001-sa-actor-lookup-quota-versions.md (status=open, category=limitation, priority=medium, source=todo-029)

Из ревью

/reviewer: NOTE -- в pool_repository.py есть N+1 в list_pools (см. строку 142). Не блокирует.
→ /backlog add N+1 в PostgresPoolRepository.list_pools -- joinedload(items) для устранения, src/.../pool_repository.py:142
   → создан docs/backlog/002-n-plus-1-pool-repository-list.md (category=optimization, source=reviewer)

Из планирования

/teamlead: при планировании Phase 5 todo-029 решено отложить multi-resource stacked-view в матрице планирования.
→ /backlog add stacked-view multi-resource в /quotas/planning -- сейчас per-ресурс single-select, multi-resource view в backlog (todo-029 Q9)
   → создан docs/backlog/003-stacked-view-multi-resource-planning.md (category=ux, source=todo-029)

Закрытие

[через 2 месяца] разработка SA-lookup endpoint завершена.
→ /backlog done 001 PR#142
   → docs/backlog/001-...md: добавлен раздел Реализация с PR#142, status=done