Clarify gate в Jira: когда тикет не идёт в разработку, пока постановка не созрела

Проблема

Заказчик создаёт задачу в Jira в свободной форме: «сделайте интеграцию с ERP», «нужен отчёт по продажам», «ускорьте каталог». Разработка и агент в IDE получают этот текст как вход — и либо уходят в неверную реализацию, либо недели уточняют в мессенджерах то, что не попадает в систему учёта.

Корень не в модели — как в разборе #01 про «интеграцию с ERP»: постановка неявна — нет границ, нет проверяемых критериев готовности, нет ответа на «что именно считается сделанным». Уточнения в Slack не привязаны к тикету: не масштабируются и не версионируются вместе с задачей.

Нужен clarify gate на уровне процесса: задача не переходит в разработку, пока в Jira не зафиксированы цель, scope и acceptance criteria, согласованные с заказчиком.

Как это выглядит в проде

Типовой контур внедрения (один Jira project = один context profile):

[Jira Cloud]  issue created / comment
      ↓ webhook
[Relay / API GW]  (опционально: auth, rate limit, PII redaction)
      ↓ POST /webhooks/jira/*
[Clarify service]  ElicitationEngine + LLM
      ↓ JiraPort
[Jira Cloud]  comments, description, transition → Ready for dev

[Git]  project bible (L1) + corpus export (L2)
[Jira REST / JQL]  похожие закрытые тикеты (L3)

Владельцы

Что измерять после внедрения

Ориентиры, не обещания из коробки:

• доля Story/Bug, ушедших в dev без явных AC в description;
• число раундов clarify до approve;
• % тикетов, возвращённых в clarify после ревью постановки;
• эскалации PO («заказчик не отвечает N раундов»).

Публичный репозиторий в этом howto — воспроизводимый след механики и контракт webhook'ов, не готовый «бот в вашей Jira из коробки».

Методика

Граница howto: контур заказчик → Jira → агент до зрелого тикета. Что команда делает после Ready for dev, — вне разбора; в репозитории следующий слой — SDD через Spec Kit (#12).

Clarify gate

Фаза clarify живёт в issue: агент ведёт структурированный диалог в комментариях (или выделенном поле), пока не выполнены критерии «постановка готова». Это gate по аналогии с eval перед релизом (разбор #10): плохой вход не проходит дальше.

Принципы

1. 1. Один issue — один след уточнений. Весь диалог в Jira. История видна заказчику, PM и разработчику; при смене исполнителя контекст не теряется.
2. 2. Вопросы по осям. Scope, акторы, данные, NFR, зависимости, AC — закрыть пробелы, без свободного чата.
3. 3. Явный критерий готовности. В description: цель, scope, проверяемые AC, помеченные риски. До этого — статус «Needs clarification», разработка не стартует.
4. 4. Человек в контуре. Бот предлагает черновик description; заказчик или PO подтверждает (approve). Без автозаписи «как сказал ИИ» в продакшн-поле.
5. 5. Выход — зрелый тикет. Description + AC в Jira — то, что уходит в разработку; черновик «для переноса в Confluence» здесь не цель.

Project context (почему без него gate слабый)

Без контекста агент задаёт универсальные вопросы — заказчик отвечает так же абстрактно. Project context — управляемая подложка: на каждый раунд собирается context pack (issue + релевантные фрагменты), без заливки всего Confluence в промпт.

L1 не автогенерируют из Confluence целиком. L2 в проде — retrieval (keyword → hybrid, см. разбор #3). L3 — JQL.

Заземлённые вопросы (redacted intake, каталог B2B)

Сырой тикет: «отчёт по каталогу B2B за квартал, желательно быстро, может ERP».

Без context pack часто остаётся: «Какие системы затронуты?»

С context pack (фрагменты из bible + corpus + PROJ-89):

1. В архитектуре каталог — Elasticsearch и B2B-витрина в PostgreSQL. Отчёт по полному индексу или только по витрине?
2. SLA витрины p99 200 ms — жёсткое ограничение и для пакетной выгрузки?
3. PROJ-89 закрывал квартальный отчёт B2B — расширение или новая выгрузка?
4. В глоссарии ERP — 1С и SAP; интеграция в scope этого тикета?
5. В документации нет политики PII для отчётов — срок хранения и доступ?

Заказчику — бизнес-язык. Citations (bible#nfr, PROJ-89) — в internal log аудита, не в теле комментария.

Фрагмент clarify в issue

Сценарий из reference trace · redacted intake · стилизация под Jira Cloud (не скриншот продукта)

Citations к bible и закрытым тикетам попадают в internalLog — в комментарии заказчику остаётся только бизнес-формулировка.

Конвейер на раунд

Parse issue → route (какие уровни контекста) → retrieve (pack)
→ gap analysis → 3–5 вопросов → ответ в комментарии
→ gap analysis → черновик description + AC + diff «было / предлагаю»
→ approve → transition Ready for dev

Профиль на project (profile.yaml): пути bible/corpus, лимит вопросов за раунд, политика citations. Один файл — один Jira project.

Артефакт

github.com/dobryakov/jira-clarify-bot — Python, FastAPI, Docker. В git — механика clarify gate, контракт webhook'ов (openapi.yaml, JSON Schema) и прогон без вызовов *.atlassian.net.

Вне репозитория — то, что привязано к вашему стенду:

• регистрация webhook и авторизация в Jira Cloud;
• клиент Atlassian REST / ADF и маппинг кастомных полей AC;
• боевой pipeline корпуса (L2) и расписание его обновления;
• multi-tenant, изоляция данных, SLA.

У разных команд эти части устроены по-разному — в git фиксируется только воспроизводимая механика и контракт входа.

Redacted context в репо (context/demo-shop/) моделирует продовый bible/corpus для e-commerce intake — те же оси вопросов, что в примере выше.

После согласованного approve в следе: description с goal/scope, измеримые AC (например: «≤ 15 min для 50k SKU», «CSV в s3://…», «без PII»), статус Ready for dev, internalLog с citations.

Для кого и почему

PO, CTO, Head of AI: качество входа в delivery поднимается в Jira, без нового инструмента для заказчика. Архитектурно это gate на intake. Отличие от cross-org agent negotiation (#2): внутренний clarify «бизнес ↔ агент» в одном issue, без cross-org переговоров по API.

Ссылки:

• github.com/dobryakov/jira-clarify-bot — репозиторий с примером
• Retrieval для L2 в проде: разбор #3 — hybrid-search
• После зрелого тикета — спеки в git: разбор #12 — Spec Kit