| 1 | # ADR 0014: Ситуационные чеклисты (модель, триггеры, UI) |
| 2 | |
| 3 | **Статус:** Accepted |
| 4 | **Дата:** 2026-04-02 |
| 5 | |
| 6 | ## Связанные ADR |
| 7 | |
| 8 | | ADR | Роль | |
| 9 | |-----|------| |
| 10 | | [0013](0013-command-surface-and-discoverability.md) | палитра и поверхность команд — родительское решение | |
| 11 | | [0010](0010-ui-modes-toml-configuration.md) | режимы | |
| 12 | | [0011](0011-debug-situational-awareness.md) | полоска состояния vs чеклист шагов | |
| 13 | | [0002](0002-debug-human-agent-parity.md) | Единый слой состояния отладки для человека и агента | |
| 14 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | Стабильные контракты MCP и тестируемая инфраструктура | |
| 15 | ## Резюме |
| 16 | |
| 17 | - Ситуационные **чеклисты**: модель, триггеры, UI; дочерний к [0013](0013-command-surface-and-discoverability.md). |
| 18 | - Discoverability через палитру и контекст задачи, не отдельное приложение. |
| 19 | |
| 20 | |
| 21 | ## Разделение с [0013](0013-command-surface-and-discoverability.md) |
| 22 | |
| 23 | - **[0013](0013-command-surface-and-discoverability.md)** — поверхность команд: палитра, discoverability в целом, минимальный toolbar. |
| 24 | - **0014 (этот ADR)** — **ситуационные чеклисты**: каталог сценариев, триггеры, привязка шагов к `command_id`, поведение карточки в UI. |
| 25 | |
| 26 | --- |
| 27 | ## Контекст |
| 28 | |
| 29 | [0013](0013-command-surface-and-discoverability.md) вводит discoverability не только через поиск по палитре и предлагает **мини-чеклисты** как аналог ситуационных подсказок (в т.ч. авиационный образ). Этот ADR фиксирует **отдельно** механику чеклистов: иначе смешиваются уровень «какие бывают точки входа» (0013) и уровень «как устроен один сценарий из шагов». |
| 30 | |
| 31 | ## Решение |
| 32 | |
| 33 | Чеклист — не замена палитры, а **узкий слой** «что имеет смысл сделать *сейчас* в этой ситуации», даже если пользователь не знает имён команд. Детали — в разделе [«Видение: механика»](#checklist-vision) ниже. |
| 34 | |
| 35 | <a id="checklist-vision"></a> |
| 36 | |
| 37 | ## Видение: механика ситуационных чеклистов |
| 38 | |
| 39 | Ниже — целевое видение реализации (итерации и состав чеклистов — по плану). |
| 40 | |
| 41 | ### Роли трёх механизмов |
| 42 | |
| 43 | | Механизм | Назначение | |
| 44 | |----------|------------| |
| 45 | | **Палитра команд** | Найти **любую** известную команду по имени / подстроке / хоткею. | |
| 46 | | **Ситуационный чеклист** | Показать **короткий упорядоченный сценарий** для текущего контекста; ответ на «что обычно делают дальше», а не на «какие команды есть в продукте». | |
| 47 | | **Toolbar** | Редкие **якорные** действия; не переносить сюда весь сценарий. | |
| 48 | |
| 49 | Шаг чеклиста с привязкой к команде вызывает **ту же** операцию, что палитра и (по контракту) автоматизация — через **единый реестр** (`command_id`) из [0013](0013-command-surface-and-discoverability.md) / [0008](0008-mcp-contracts-and-testable-infrastructure.md). |
| 50 | |
| 51 | ### Логическая модель чеклиста |
| 52 | |
| 53 | - **`checklist_id`** — стабильный идентификатор (телеметрия, привязка к режиму, эволюция контента). |
| 54 | - **`situation`** — условие релевантности (см. триггеры ниже). |
| 55 | - **`steps[]`** — упорядоченные шаги: человекочитаемый текст; опционально **`command_id`** из реестра; опционально **deep link** (открыть панель, файл, настройку). |
| 56 | - **Состояние шага в UI** (сессия или с сохранением в настройках — по итерации): например `todo` / `done` / `skipped` / `na`. |
| 57 | - **`anchors`** — где чеклист *может* показываться (компактная карточка у края редактора, полоска, модал «первый раз» и т.д.); один сценарий не обязан быть привязан к одному виджету навсегда. |
| 58 | |
| 59 | Чеклист **направляет внимание** и при клике делегирует в слой команд; не обязан «выполнять магию» в обход реестра. |
| 60 | |
| 61 | ### Когда чеклист релевантен (триггеры) |
| 62 | |
| 63 | Правила задаются **декларативно в TOML** — в том же духе, что конфигурация UI-режимов ([0010](0010-ui-modes-toml-configuration.md)); отдельный JSON как параллельный «официальный» формат для этого **не нужен** (см. позицию 0010 по одному текстовому стеку конфигов). Условия показа — структура вроде `when` с полями `ui_mode`, `phase`, событие и т.д. (точная схема — при реализации), без логики в VM. |
| 64 | |
| 65 | - **Режим UI** ([0010](0010-ui-modes-toml-configuration.md)) — например в Debug показывать сценарий «типичный цикл отладки». |
| 66 | - **Фаза сценария** — машина состояний высокого уровня (`нет решения` → `сборка` → `отладка` → …); у фазы — свой чеклист или ветка шагов. |
| 67 | - **Событие** — первый запуск, первый брейкпоинт за сессию, падение сборки и т.п. |
| 68 | - **Явный запрос** — «Показать чеклист…» из палитры или контекстного меню. |
| 69 | |
| 70 | ### Поведение в UI |
| 71 | |
| 72 | - По умолчанию — **компактная карточка** (сворачиваемая), не полноэкранный wizard; визуальный ориентир — мокап в [docs/ui-ux/concept-screens/cascade-ide-checklist-ui-concept.png](../ui-ux/concept-screens/cascade-ide-checklist-ui-concept.png). |
| 73 | - Клик по шагу с `command_id` = тот же вызов, что из палитры; отметка шага `done` — вручную и/или эвристически после успешной команды (сложность — по итерации). |
| 74 | - **Не мешать:** «Скрыть» / «не показывать для этого сценария» без потери возможности открыть снова из палитры. |
| 75 | - **Связь с [0011](0011-debug-situational-awareness.md):** полоска осведомлённости — про *состояние*; чеклист — про *типичные следующие шаги* в сценарии. Не смешивать длинный лог и длинный чеклист в одной зоне. |
| 76 | |
| 77 | ### Поток данных (целевой) |
| 78 | |
| 79 | ```mermaid |
| 80 | flowchart LR |
| 81 | subgraph triggers [Триггеры] |
| 82 | Mode[UI mode] |
| 83 | Phase[Фаза сценария] |
| 84 | Event[Событие] |
| 85 | end |
| 86 | subgraph core [Ядро] |
| 87 | Registry[Реестр команд] |
| 88 | Catalog[Каталог чеклистов] |
| 89 | end |
| 90 | subgraph ui [UI] |
| 91 | Palette[Палитра] |
| 92 | Checklist[Чеклист] |
| 93 | end |
| 94 | triggers --> Catalog |
| 95 | Catalog --> Checklist |
| 96 | Registry --> Palette |
| 97 | Registry --> Checklist |
| 98 | Checklist -->|command_id| Registry |
| 99 | ``` |
| 100 | |
| 101 | ### Вне ближайшего объёма v1 |
| 102 | |
| 103 | - Длинные «авиационные» preflight-листы на десятки пунктов для каждого действия. |
| 104 | - Встроенная база знаний внутри чеклиста (кроме ссылок на команды и внешнюю документацию). |
| 105 | - Обязательная синхронизация «галочек» чеклиста с агентом: паритет по **командам** ([0002](0002-debug-human-agent-parity.md)); состояние чеклиста для человека может оставаться локальным до отдельного решения. |
| 106 | |
| 107 | ### Порядок внедрения (рекомендация) |
| 108 | |
| 109 | 1. **Реестр команд + палитра** ([0013](0013-command-surface-and-discoverability.md)) — общая база для toolbar, MCP и шагов чеклиста. |
| 110 | 2. **Каталог чеклистов + карточка UI** — шаги с `command_id`, триггеры и скрытие по правилам выше. |
| 111 | |
| 112 | ## Последствия |
| 113 | |
| 114 | - Нужен **каталог сценариев** (описание шагов, `command_id`, правила `situation`) поверх **единого реестра команд**; иначе чеклист станет вторым источником правды. |
| 115 | - Чеклист в UI — **представление вызовов** через тот же реестр, что палитра и MCP. |
| 116 | - Тесты и сценарии документации (позже): какие чеклисты в каких режимах показываются по умолчанию. |
| 117 | |
| 118 | ## Отклонённые альтернативы (как финальное состояние) |
| 119 | |
| 120 | - **Чеклист как отдельный канал команд** без `command_id` и без реестра — отклонено: расхождение с палитрой и агентом. |
| 121 | - **Только длинные чеклисты** без палитры — отклонено: см. [0013](0013-command-surface-and-discoverability.md). |
| 122 | |
| 123 | ## Обсуждение (открытые вопросы для следующих итераций) |
| 124 | |
| 125 | - Состав **сценариев** по режимам UI и пересечение с [0011](0011-debug-situational-awareness.md) / [0012](0012-floating-workspace-chrome.md) (где физически показывать карточку при плавающем хроме). |
| 126 | - Нужен ли **отдельный** UX для «первого запуска» vs «второй день». |
| 127 | |