Debt

---
name: debt
description: 'Record a technical-debt item (DEBT-NNN) — registration only by default, or register + auto-generate a fix TASK with --task. Use when PM mentions "add tech debt", "record tech debt", "technical debt", "tech debt item", "refactor tracking", "технический долг", "запиши техдолг", or any request to capture deferred refactoring / cleanup work. Trigger liberally — under-triggering loses debt visibility; over-triggering is recoverable (PM can delete or defer).'
argument-hint: "[описание] [--task]"
---

# /polisade:debt [описание] [--task] — Добавить техдолг

Быстрое добавление технического долга. По умолчанию создаёт **только DEBT**
(регистрация). Передай `--task`, чтобы сразу завести связанную TASK и положить
её в `readyToWork`.

## Использование

```
/polisade:debt Рефакторинг модуля авторизации
/polisade:debt Обновить зависимости до последних версий
/polisade:debt Добавить индексы в БД --task          # сразу создать TASK
```

- Без флага — создаётся только DEBT со статусом `ready`. Для последующей
  декомпозиции в TASK используй `/polisade:tasks DEBT-XXX` (когда готов
  работать над долгом).
- С `--task` — создаётся пара `DEBT + TASK`, TASK добавляется в
  `readyToWork` (поведение симметрично старому default).

## Алгоритм

1. **Распарсь args.** Выдели `--task` (если есть), остаток склей в описание.
2. **Прочитай `.state/PROJECT_STATE.json`.** Извлеки `settings.debt.autoCreateTask`
   (default: `false` если ключ отсутствует).
3. **Определи `create_task`:**
   - `create_task = true` если args содержит `--task` **или**
     `settings.debt.autoCreateTask == true`.
   - `create_task = false` во всех остальных случаях.
   - **У команды `/polisade:debt` нет флага отказа от TASK.** Чтобы получить
     поведение «только DEBT» в мигрированном проекте — PM либо выключает
     `settings.debt.autoCreateTask: false` в `.state/PROJECT_STATE.json`,
     либо принимает legacy-поведение (TASK создаётся + deprecation banner).
4. **Вычисли next-id для DEBT** по протоколу из
   `skills/tasks/references/compute-next-id.md` (единый max по
   `.state/counters.json`, `PROJECT_STATE.artifactIndex` и file-scan).
   Если `create_task` — **также вычисли next-id для TASK**. При **Counter
   drift** (на диске выше, чем в counters.json) — АБОРТ с сообщением
   «Запусти `python3 {plugin_root}/scripts/polisade_sync.py . --apply --yes`
   и повтори». Ни одного файла не пиши до устранения drift'а.
5. **Write-guard.** Перед `Write` проверь, что `backlog/tech-debt/DEBT-{N}-slug.md`
   не существует и `DEBT-{N}` отсутствует в `state.artifactIndex` (и
   legacy `state.artifacts`). Если `create_task` — ту же проверку на
   `tasks/TASK-{M}-slug.md` / `TASK-{M}`. При коллизии — АБОРТ
   с отсылкой к `/polisade:sync --apply`.
6. **Создай `backlog/tech-debt/DEBT-XXX-slug.md`** по шаблону ниже.
   Определи категорию автоматически или спроси.
7. **Если `create_task` — создай `tasks/TASK-XXX-slug.md`** со ссылкой
   на DEBT. Прочитай файлы из «Предлагаемое решение» DEBT, найди
   конкретные функции/классы, впиши в TASK точные пути + идентификаторы.

   ⛔ **КРИТИЧНО: TASK-файл ДОЛЖЕН быть ровно `tasks/TASK-XXX-*.md` в корневой папке `tasks/`.**
   НЕ в `docs/tasks/`, НЕ в `docs/TASK-*.md`, НЕ в `backlog/tasks/`.
   `/polisade:implement` ищет таски ТОЛЬКО в корневой `tasks/`. Если папки нет — `mkdir -p tasks`.
8. **Инкрементируй счётчики.** `counters.json[DEBT] = N_debt` всегда;
   `counters.json[TASK] = N_task` — только если `create_task`.
   Фиксируй именно next-id из шага 4.
9. **Обнови `.state/PROJECT_STATE.json`:**
   - Добавь DEBT со статусом `ready` (в `artifactIndex`).
   - Если `create_task` — добавь TASK со статусом `ready` в
     `readyToWork` и в `artifactIndex`, пропиши `parent: DEBT-XXX`.
10. **Выведи подтверждение строго по таблице:**

    | `create_task` | `--task` передан? | Блок подтверждения | Deprecation banner? |
    |---|---|---|---|
    | `false` | нет | «ТЕХДОЛГ ЗАРЕГИСТРИРОВАН» (без TASK) | нет |
    | `true` | **да** | «ТЕХДОЛГ ДОБАВЛЕН» (с TASK) | нет |
    | `true` | **нет** (legacy `autoCreateTask: true`) | «ТЕХДОЛГ ДОБАВЛЕН» (с TASK) | **да**, поверх блока |

    ⛔ **Частая ошибка:** показать deprecation banner и блок «ЗАРЕГИСТРИРОВАН»
    (без TASK) одновременно — это **внутреннее противоречие**: banner
    предупреждает о легаси-создании TASK, которая уже создана на шагах 6-9,
    поэтому блок должен быть именно «ДОБАВЛЕН» с TASK. Banner не отменяет
    создание TASK, он только сигнализирует PM о переходе на новый default.

## Opt-in TASK: флаг vs настройка

`/polisade:debt` по умолчанию **только регистрирует** долг — это важное
изменение с v2.21.0. Логика opt-in:

| Источник сигнала | Поведение |
|---|---|
| `/polisade:debt <d>` + `settings.debt.autoCreateTask: false` (новый проект) | Только DEBT |
| `/polisade:debt <d> --task` | DEBT + TASK (флаг явный) |
| `/polisade:debt <d>` + `settings.debt.autoCreateTask: true` (мигрированный) | DEBT + TASK + deprecation warning |
| `/polisade:debt <d> --task` + настройка любая | DEBT + TASK (флаг побеждает) |

Когда понадобилась TASK уже после регистрации — `/polisade:tasks DEBT-XXX`
декомпозирует DEBT в 1-3 атомарных TASK (pattern как у BUG).

## Категории техдолга

| Категория | Примеры |
|-----------|---------|
| refactoring | Улучшение структуры кода, разделение модулей |
| dependencies | Обновление библиотек, миграция версий |
| performance | Оптимизация запросов, кэширование |
| security | Улучшение безопасности, аудит |
| testing | Добавление тестов, улучшение покрытия |
| infrastructure | CI/CD, конфигурация, мониторинг |

## Шаблон файла DEBT

```markdown
---
id: DEBT-XXX
title: "[Описание]"
status: ready
created: YYYY-MM-DD
priority: P3
category: refactoring
task: null  # TASK-XXX (опционально — при --task или через /polisade:tasks DEBT-XXX)
---

# Tech Debt: [Описание]

## Описание

[Описание из команды]

## Почему это важно

[Какие проблемы создаёт текущее состояние]

## Предлагаемое решение

[Как исправить]

## Риски

[Что может пойти не так]

## Критерии готовности

- [ ] [Конкретный критерий]
- [ ] Тесты проходят
- [ ] Код ревью пройден
```

## Шаблон TASK при `--task`

Используется **только** когда TASK создаётся одновременно с DEBT — по
флагу `--task` или из-за `settings.debt.autoCreateTask: true`. Без флага
этот шаблон не применяется.

```markdown
---
id: TASK-XXX
title: "[Описание техдолга]"
status: ready
created: YYYY-MM-DD
parent: DEBT-XXX
priority: P3
depends_on: []
---

# Задача: [Описание]

## Контекст

**DEBT:** [[DEBT-XXX]]
**Зачем:** [Какую проблему решает этот рефакторинг]

## Scope

**Входит:** [конкретные файлы/модули для рефакторинга]
**НЕ входит:** [что трогать НЕ нужно, даже если похоже]

## Что нужно сделать

[Уточнённое из DEBT с конкретными файлами/функциями]

## Критерии приёмки

- [ ] [Фальсифицируемый критерий — проверяемый YES/NO]
- [ ] Тесты проходят
- [ ] Существующее поведение сохранено

## Verification

```bash
# Команды для проверки что рефакторинг не сломал поведение
```
```

## Формат подтверждения

### Без TASK (default)

```
═══════════════════════════════════════════
ТЕХДОЛГ ЗАРЕГИСТРИРОВАН
═══════════════════════════════════════════

ID: DEBT-001
Описание: Рефакторинг модуля авторизации
Файл: backlog/tech-debt/DEBT-001-auth-refactor.md
Категория: refactoring
Приоритет: P3
Статус: ready

TASK не создана — долг зафиксирован для планирования.

═══════════════════════════════════════════
СЛЕДУЮЩИЕ ШАГИ:
   → /polisade:tasks DEBT-001 — декомпозировать в TASK-и когда готов
   → /polisade:debt <описание> --task — в следующий раз создать TASK сразу
   → /polisade:state — обзор бэклога
═══════════════════════════════════════════
```

### С TASK (`--task` или legacy `autoCreateTask: true`)

Этот блок используется для **ОБОИХ** случаев, когда TASK создана —
по явному флагу `--task` или из-за legacy-настройки. Заголовок всегда
«ТЕХДОЛГ ДОБАВЛЕН» (не «ЗАРЕГИСТРИРОВАН»), потому что TASK реально
создаётся на шагах 6-9 и лежит в `readyToWork`.

```
═══════════════════════════════════════════
ТЕХДОЛГ ДОБАВЛЕН
═══════════════════════════════════════════

ID: DEBT-001
Описание: Рефакторинг модуля авторизации
Файл: backlog/tech-debt/DEBT-001-auth-refactor.md
Категория: refactoring
Приоритет: P3
Статус: ready

Создана задача: TASK-001
Файл: tasks/TASK-001-auth-refactor.md

═══════════════════════════════════════════
СЛЕДУЮЩИЙ ШАГ:
   → /polisade:implement TASK-001 — выполнить сразу
   → /polisade:continue — автономная работа
   → /polisade:state для обзора бэклога
═══════════════════════════════════════════
```

### Deprecation banner (только в legacy-ветке: `autoCreateTask: true` + без `--task`)

Добавляй **в самом начале** вывода, **поверх** блока «ТЕХДОЛГ ДОБАВЛЕН»
(см. таблицу в шаге 10 алгоритма). TASK при этом **создаётся** — banner
не отменяет поведение, а только предупреждает о планируемом удалении
legacy-пути.

```
⚠️  DEPRECATION WARNING
─────────────────────────────────────────
TASK создана автоматически из-за legacy-настройки
`settings.debt.autoCreateTask: true` (унаследована при миграции
проекта). В следующей minor-версии Polisade Orchestrator это
поведение будет удалено.

Чтобы перейти на новый default уже сейчас:
  • отредактируй `.state/PROJECT_STATE.json` →
    `settings.debt.autoCreateTask: false`
  • используй флаг `/polisade:debt <описание> --task` когда TASK нужна
  • используй `/polisade:tasks DEBT-XXX` для ленивой декомпозиции
─────────────────────────────────────────
```

## Приоритет техдолга

По умолчанию техдолг получает **P3** — ниже фич и багов.

Исключения:
- Security issues → P1
- Critical performance → P1
- Blocking dependencies → P2

## Важно

- По умолчанию `/polisade:debt` **не создаёт TASK** — только регистрирует долг.
  Используй `--task` или `/polisade:tasks DEBT-XXX` для создания задачи.
- `/polisade:implement` работает только с TASK-XXX.
- `/polisade:implement DEBT-XXX` deprecated — всё ещё работает и создаст TASK,
  если её нет, потому что это явная opt-in команда на работу
  (PM прямо просит реализовать артефакт).
- Хороший момент для техдолга — между фичами или в конце спринта.
- Мигрированные проекты (`settings.debt.autoCreateTask: true`) продолжают
  получать автосозданную TASK, но с deprecation-баннером до момента,
  когда PM переключит настройку.