agentsclimarketplace
Sign in

Debt

Skill cryndoc/polisade-orchestrator/skills/debt

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).From its SKILL.md

Install
npx -y skills add cryndoc/polisade-orchestrator --skill debt

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

15.0 KB, as published. Nobody here has run it

/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> --taskDEBT + 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Добавление тестов, улучшение покрытия
infrastructureCI/CD, конфигурация, мониторинг

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

---
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. Без флага этот шаблон не применяется.

---
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 переключит настройку.

Keep looking

Skills are one crate of 627,801. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.