# Спецификация файла исследования (Markdown)

Версия 1.0 · принята 2026-09-19. Определяет точную форму файла `research.md`,
который модель создаёт в своей рабочей папке. Содержательные требования к разделам —
в [research-standard.md](research-standard.md). Файл проверяется валидатором
автоматически; отклонения от формы блокируют приёмку.

## 1. Файл

- Имя: `research.md`, кодировка UTF-8, переводы строк LF.
- Расположение: корень рабочей папки модели. Дополнительные файлы (приложения,
  черновики) допускаются, но всё обязательное содержится в `research.md`.
- Язык: русский. Названия методов, продуктов, ролей и артефактов в оригинале.

## 2. Front matter

Файл начинается с YAML front matter между строками `---`:

```yaml
---
title: "Название исследования"
slug: "slug-темы"
participant: astra            # astra | opus (в темах по 2026-09-22 — fable)
model: "gpt-6-astra"          # фактическая модель
effort: "ultra"               # уровень effort запуска
date: 2026-09-19              # дата запуска
cutoff: 2026-09-19            # дата среза, равна дате запуска
language: ru
sources_read: 31              # число источников в реестре
status: complete              # complete | partial
summary: "Две-три фразы для каталога: что это, главный вывод, ключевое ограничение."
---
```

Все поля обязательны. `status: partial` требует объяснения в разделе 12.

## 3. Разделы

После front matter идёт один заголовок первого уровня с названием, затем ровно
пятнадцать заголовков второго уровня в указанном порядке, с указанными
идентификаторами в фигурных скобках. Заголовок пишется буквально, идентификатор
используется для якорей и проверки.

```markdown
# Название исследования

## 0. Вердикт {#verdict}
## 1. Что это и как работает {#basics}
## 2. Актуальность и доказательная база на дату среза {#evidence}
## 3. Где применимо и где нет, плюсы и минусы {#fit}
## 4. Альтернативы и дерево решений {#alternatives}
## 5. Практическое применение {#practice}
## 6. Артефакты {#artifacts}
## 7. С чем используется в связке {#combo}
## 8. Метрики здоровья и антипаттерны {#health}
## 9. Инструменты и софт {#tools}
## 10. Адаптация под LLM и агентов {#llm}
## 11. Происхождение, ключевые фигуры, что читать {#origins}
## 12. Открытые вопросы и границы уверенности {#open-questions}
## 13. Реестр источников {#sources}
## 14. Словарь терминов {#glossary}
```

Условные разделы `artifacts`, `tools`, `llm` присутствуют всегда. Если раздел
неприменим, его тело состоит из одной строки:

```markdown
Не применимо: <причина в одном-двух предложениях>.
```

Внутри разделов допускаются заголовки третьего и четвёртого уровня, списки,
таблицы, цитаты, блоки кода. Заголовки второго уровня внутри тела запрещены.

## 4. Ссылки на источники и типы утверждений

Ссылка на источник ставится сразу после утверждения и содержит идентификатор
строки реестра: `[S12]` или несколько через запятую `[S3, S7]`. Идентификаторы
начинаются с `S1` и идут подряд без пропусков.

Тип существенного утверждения ставится в фигурных скобках после предложения,
перед ссылкой или после неё:

```markdown
Метод впервые описан в 1987 году {факт} [S1].
Производитель заявляет сокращение времени на 40 % {вендор} [S9].
Рандомизированное исследование на 120 участниках не нашло эффекта {эмпирика} [S4].
Практики считают ежедневный ритуал избыточным для команд до трёх человек {мнение} [S6, S11].
Вероятно, различие объясняется составом выборки {гипотеза}.
```

Допустимые типы: `{факт}`, `{вендор}`, `{эмпирика}`, `{мнение}`, `{гипотеза}`.
Другие слова в фигурных скобках не используются. Утверждение с типом `{гипотеза}`
может не иметь ссылки; остальные типы требуют хотя бы одну ссылку `[S..]`.

## 5. Обязательные структуры внутри разделов

### Раздел 3: плюсы и минусы

Четыре подзаголовка третьего уровня, каждый со списком:

```markdown
### Подходит, когда
- **Условие.** Почему именно здесь работает.

### Не подходит, когда
- **Условие.** Что ломается и почему.

### Плюсы
- **Плюс.** Механизм.

### Минусы
- **Минус.** Механизм и цена.
```

### Раздел 4: сравнительная таблица и дерево решений

Сравнительная таблица в формате Markdown с предметом исследования в первой строке
данных. Затем подзаголовок `### Дерево решений` и вложенный список правил.
Каждый пункт содержит условие и результат, разделённые стрелкой `→`:

```markdown
### Дерево решений
- Если команда меньше пяти человек → выбирайте A
  - Если нет выделенного владельца → выбирайте A в упрощённой форме
  - Иначе → полная форма A
- Если требуется внешняя отчётность → выбирайте B
- Иначе → предмет исследования
```

Лист дерева называет конкретный выбор. Формулировка «зависит от ситуации»
в листе не допускается.

### Раздел 8: таблица здоровья

Таблица с колонками «Признак», «Здоровая норма», «Симптом деградации»,
«Источник». Затем подзаголовок `### Антипаттерны` и для каждого антипаттерна
заголовок четвёртого уровня и четыре подписанных абзаца: «Как выглядит»,
«Почему возникает», «Как чинить», «Когда менять практику».

### Раздел 13: реестр источников

Единственная таблица с фиксированными колонками:

```markdown
| ID | Название | Автор или издатель | URL | Дата публикации | Дата доступа | Доступ | Что подтверждает |
|---|---|---|---|---|---|---|---|
| S1 | Название документа | Автор, издатель | https://... | 2024-05-12 | 2026-09-19 | полный текст | раздел 1: определение; раздел 11: происхождение |
| S2 | Название страницы | Издатель | https://... | без даты | 2026-09-19 | фрагмент | раздел 2: доля рынка (вендор) |
```

Правила колонок:

- `ID`: `S1`, `S2`, … без пропусков, в порядке первого упоминания в тексте.
- `URL`: реальный адрес, по которому источник открывался. Для книг без
  онлайн-версии — адрес издательской страницы или каталога с пометкой в колонке «Доступ».
- `Дата публикации`: `ГГГГ-ММ-ДД`, `ГГГГ-ММ`, `ГГГГ` или `без даты`.
- `Дата доступа`: `ГГГГ-ММ-ДД`, реальная дата обращения.
- `Доступ`: `полный текст`, `фрагмент`, `аннотация`, `недоступен`.
- `Что подтверждает`: номера разделов и суть утверждений.

### Раздел 14: словарь терминов

Список, каждый пункт начинается с термина жирным, затем русское пояснение
в скобках, двоеточие и определение:

```markdown
- **Term** (русское пояснение): определение в контексте предмета исследования.
```

## 6. Общие правила оформления

- Перечисления оформляются списками, а не через точку с запятой в предложении.
- Сравнения и наборы параметров оформляются таблицами.
- В содержательном абзаце главное выделено жирным один раз.
- Не более четырёх предложений подряд без структурного элемента (список,
  таблица, заголовок, цитата).
- Прямые цитаты короткие, в кавычках, со ссылкой на источник.
- Иллюстративные числа помечаются словами «иллюстрация» или «пример» в том же предложении.

## 7. Чек-лист самопроверки перед завершением

1. Front matter полный, `sources_read` равен числу строк реестра.
2. Пятнадцать заголовков второго уровня в заданном порядке с заданными id.
3. Условные разделы заполнены или содержат строку «Не применимо: причина».
4. Каждый `[S..]` в тексте есть в реестре; каждый источник реестра упомянут в тексте.
5. У каждого источника есть URL, дата публикации или «без даты», дата доступа, вид доступа.
6. Существенные утверждения имеют тип в фигурных скобках и ссылку.
7. Дерево решений доводит до конкретного выбора.
8. Словарь содержит все термины, требующие пояснения.
9. Нет «TODO», «TBD», «дописать», пустых разделов и заглушек.
10. Числа согласованы между разделами.
