fix(issue): align headings with create-issue validation and add SDD sections (#169 )

* fix(issue): align headings with create-issue validation and add SDD sections

* docs(issue): add handoff, ADR, and fix CI for SDD validation

* docs(pr-169): fix handoff sections

---------

Co-authored-by: opencode-agent <agent@opencode.local>

2026-07-31 19:42:14 +03:00

3.8 KiB

Raw Blame History

ADR-071: 7 mandatory SDD sections for all issues

Статус

Accepted (2026-07-31)

Контекст

Шаблоны issue body в issue/SKILL.md и spec/SKILL.md использовали заголовки (## Что сделать, ## Проверка, ## Acceptance criteria), не совпадающие с валидацией create-issue.ts (## Контекст, ## Задача, ## Критерии приемки). Issues, созданные по шаблону скилла, проваливали валидацию tool'а — агент получал ошибку вместо создания issue.

Кроме того, 3 обязательные секции (Контекст, Задача, Критерии приемки) не покрывали SDD-аспекты: контракты (ожидаемое поведение/API), инварианты (правила без исключений), граничные случаи (что при ошибках), out-of-scope (что НЕ делаем). Без этих секций агент угадывает границы задачи, что приводит к scope creep и неполным результатам.

Решение

Унифицировать все шаблоны и валидацию на 7 обязательных SDD-секций — всегда, без флагов и режимов:

## Контекст — зачем + текущее состояние
## Задача — что делаем
## Контракты — ожидаемое поведение / API
## Инварианты — правила без исключений
## Граничные случаи — что при ошибках
## Вне scope — что НЕ делаем
## Критерии приемки — как проверяем

Изменения:

create-issue.ts: 4 новые проверки заголовков (всегда, без флагов).
issue/SKILL.md: шаблон 7 секций, обновлённые примеры.
spec/SKILL.md: шаблон issue body обновлён до 7 секций.
bug-discovery/SKILL.md: описание заголовков обновлено.
Тесты (Python + TS): VALID_BODY 7 секций, 4 новых missing-heading теста.

Альтернативы

Двухрежимный подход (sdd flag) — create-issue принимает sdd?: boolean, при true проверяет 7 секций, при false — 3. Отклонено: флаги создают два стандарта, агенты путаются какой режим выбрать, SDD-секции полезны для всех задач (даже кратко).
Оставить 3 секции — отклонено: не покрывает контракты, инварианты, edge cases, out-of-scope. Агент угадывает границы → scope creep.
Опциональные SDD-секции (предупреждение, не error) — отклонено: предупреждения игнорируются агентами. Только жёсткая валидация гарантирует качество.

Последствия

Все новые issues должны содержать 7 секций — включая баг-репорты (bug-discovery скилл обновлён).
Существующие issues в репо не соответствуют новому формату — это не влияет на функциональность, только на создание новых.
SDD-секции можно заполнять кратко (1-2 строки) — главное наличие заголовка.

3.8 KiB Raw Blame History Unescape Escape