analysis-kit

Общие правила для агентов product-owner, business-analyst, system-analyst, security-reviewer и для основной сессии, когда она делает их работу сама. Разделы этого файла действуют всегда. Шаблон и чеклист конкретного артефакта лежат в references/: читай файл только того артефакта, с которым работаешь сейчас.

Каталог и имена файлов

Артефакты одной инициативы лежат в docs/analysis/<feature>/ от корня текущего проекта, то есть рабочей директории. Путь к файлу или каталогу из запроса задаёт каталог сразу; относительный путь отсчитывается от рабочей директории сессии, а не от каталога этого скилла. Иначе, если в проекте уже есть каталог с такими артефактами, работай в нём и назови путь в ответе; найти его помогает glob по **/*_brd.md, **/*_user-story.md, **/*_openapi.yaml внутри рабочей директории.

<feature> — slug инициативы латиницей в kebab-case. Ключ задачи из трекера, если пользователь его дал, идёт первым: PAY-123-sbp-refunds. Slug одинаков во всех артефактах инициативы. Если его нет ни в запросе, ни в существующих файлах, выбери короткий slug по сути инициативы и назови его в резюме.

Файл артефакта: docs/analysis/<feature>/<feature>_<тип>.<расширение>, тип и расширение берутся из таблицы владельцев. Отчёт ревью одного файла: docs/analysis/<feature>/reports/<имя проверяемого файла без расширения>_quality-review.md или ..._security-review.md; отчёт ревью всей инициативы: reports/<feature>_quality-review.md или reports/<feature>_security-review.md.

Владельцы

Артефакт создаёт и меняет только его владелец. Остальные ссылаются на него по ID. Нужна правка в чужом артефакте — опиши её в блоке «Передача».

Границы, на которых роли чаще всего пересекаются:

• User Story и Acceptance Criteria пишет product-owner. BRD ссылается на них по ID и добавляет бизнес-требования и правила, которых в историях нет. Пока историй нет, business-analyst даёт каждому BR критерий проверки и просит product-owner оформить истории.
• Ожидания бизнеса к скорости, доступности и защите данных business-analyst записывает в BRD словами бизнеса как BR типа «ожидание качества». system-analyst превращает их в измеримые NFR со ссылкой на исходный BR.
• security-reviewer пишет только отчёт. Исправления по замечаниям SEC вносит владелец артефакта.
• Ревью качества проводится по прямой просьбе. Свой артефакт проверяет владелец; system-analyst дополнительно проверяет согласованность артефактов всей инициативы.

ID и трассировка

Нумерация сквозная в пределах <feature>: перед созданием ID найди grep'ом максимальный номер этого типа в каталоге. Шаги процесса нумеруются отдельно в AS-IS и TO-BE и в ссылках пишутся с файлом. Удалённый элемент остаётся в документе зачёркнутым с причиной, ~~BR-4~~ удалено: дублирует BR-2, и его номер больше не используется.

Ссылка между артефактами — это ID, при первом упоминании в документе вместе с файлом: BR-3 (sbp-refunds_brd.md).

Факты и пробелы

Факты берутся из двух источников: слов пользователя в текущем диалоге и файлов проекта. Пробел записывается маркером [GAP: что неизвестно → кто ответит] в том месте артефакта, где нужен факт, и дублируется вопросом Q-n в разделе «Открытые вопросы». Пример: Максимальная сумма возврата: [GAP: лимит на одну операцию → product-owner].

Цифры, названия систем, сроки и номера пунктов нормативных актов пишутся только из источников. Нормативный акт, который ты знаешь без точного номера пункта, указывай без номера пункта.

Раздел шаблона, который не нужен этой инициативе, остаётся с пометкой Не применимо: <причина>. В готовом артефакте каждый раздел заполнен, помечен [GAP] или помечен Не применимо.

Не хватает чужого артефакта — делай свой с [GAP] в зависимых местах и запроси недостающее в «Передаче».

Оформление

• Текст на русском; технические термины, ключи спецификаций и имена полей на английском.
• Даты в ISO 8601 (2026-09-11), время в UTC.
• Абзац markdown пишется одной строкой, переносы делает рендерер.
• Markdown-артефакт из таблицы владельцев начинается с таблицы метаданных и заканчивается разделами «Открытые вопросы» и «История изменений». Отчёт ревью устроен по-своему: его шапка и разделы берутся из «Шаблона отчёта» в references/quality-review.md или references/security-review.md.

| Поле | Значение |
|---|---|
| Feature | `<feature>` |
| Владелец | <агент> |
| Статус | draft |
| Версия | 0.1 |
| Обновлён | YYYY-MM-DD |
| Связанные артефакты | `<файл>`, … |

• Статус draft или review ставит агент, approved ставит только человек. Каждое изменение артефакта повышает версию и добавляет строку в «Историю изменений».
• В YAML-спецификациях те же метаданные живут в info, в PlantUML и SQL — в комментарии в начале файла.

Порядок работы

1. Определи <feature> и каталог. Список файлов получи glob'ом docs/analysis/<feature>/** от рабочей директории и прочитай только найденные, включая reports/; поиск ограничен рабочей директорией. Шаг завершён, когда известно, какие артефакты уже есть, в каком они статусе и какие Q-n открыты.
2. Для каждого артефакта, который создаёшь, меняешь или проверяешь, прочитай его reference из таблицы владельцев.
3. Сделай артефакт по шаблону и правилам reference. Шаг завершён, когда в файле есть каждый раздел шаблона с тем же заголовком и в том же порядке.
4. Пройди чеклист качества из reference по результату и исправь найденное. Шаг завершён, когда каждый пункт выполнен или превращён в Q-n с [GAP].
5. Ответь в формате ниже.

Формат ответа

Это финальное сообщение вызывающему. Содержимое файлов артефактов и отчётов задаёт шаблон их reference.

Резюме: <1-3 предложения: что сделано и зачем>

Файлы:
- `<путь>`: создан | изменён | проверен — <что именно>

Находки: <проблемы, риски, противоречия между артефактами; «нет», если их нет>

Открытые вопросы:
- Q-<n> → <кому>: <вопрос>

Передача:
- → <агент>: <что сделать>; входные файлы: `<путь>`, …
- → пользователь: <какое решение нужно>

Работа передаётся только через блок «Передача»: следующего агента запускает тот, кто вызвал тебя, или пользователь. Если передавать нечего, пиши Передача: не требуется.