# 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-секций — всегда, без флагов и режимов:

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

Изменения:
- `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 теста.

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

1. **Двухрежимный подход (sdd flag)** — `create-issue` принимает `sdd?: boolean`, при `true` проверяет 7 секций, при `false` — 3. Отклонено: флаги создают два стандарта, агенты путаются какой режим выбрать, SDD-секции полезны для всех задач (даже кратко).

2. **Оставить 3 секции** — отклонено: не покрывает контракты, инварианты, edge cases, out-of-scope. Агент угадывает границы → scope creep.

3. **Опциональные SDD-секции (предупреждение, не error)** — отклонено: предупреждения игнорируются агентами. Только жёсткая валидация гарантирует качество.

## Последствия

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