---
name: gen-adr-assist
description: >-
  Creates, refines, reviews, and expands Architectural Decision Records (ADR) using project
  templates and tech-radar.json.
  Use when the user asks for ADRs, turns notes or requirements into ADR, compares architecture
  options, documents technology or integration choices.
---

# Навык `gen-adr-assist`

Используй этот навык, когда пользователь хочет **создать, доработать, проверить или расширить архитектурное решение (ADR, Architectural Decision Record)**

## Когда применять навык

Применяй навык, если пользователь просит:
- написать ADR с нуля;
- превратить заметки, переписку или требования в ADR;
- сравнить варианты и зафиксировать решение;
- оформить выбор технологии, интеграционного подхода, модели данных, платформы, средства безопасности, варианта deployment;
- сначала сделать краткий draft, а затем полный документ;
- учитывать ограничения из `tech-radar.json`.

Не применяй навык, если нужен:
- просто текст про архитектуру без фиксируемого решения;
- генерация кода без документирования решения;
- общее описание системы без выбора между альтернативами.

## Именование файлов

- Файлы ADR должны именоваться по шаблону `adr-{номер:04d}-{slugify(заголовок)}.md`, где slugify преобразует заголовок в нижний регистр, заменяет пробелы и знаки препинания на дефисы. Пример: `adr-0001-ispolzovanie-postgresql.md`.
- Папка для принятых ADR: `adr/` Не создавай в ней никаких файлов, кроме начинающхся с adr  и файлов `adr/history.log`,`adr/INDEX.md`
- Папка для новых проектов ADR `adr/proposed`
- Папка для устаревших ADR `adr/deprecated`
- Папка для замененных ADR `adr/superseded`

Добавляй в файл `adr/history.log` записи о создании ADR и изменении его статуса (переноса в соответствующий подкаталог) в формате `YYYY-MM-DD {имя adr файла} {новый статус}`


## Структура навыка

Основные материалы лежат в двух каталогах:
- `assets/` — рабочие артефакты: шаблоны, checklist, `tech-radar.json`;
- `references/` — краткие руководства и справочные материалы.

Используй прежде всего:
- `assets/adr-template.md`
- `assets/review-checklist.md`
- `assets/tech-radar.json`
- `references/question-flows.md`
- `references/adr-types.md`
- `references/adr-guide.md`
- `references/tech-radar-guide.md`

## Обязательное поведение

1. Проанализируй достаточность информации для заполнения шаблона: `assets/adr-template.md`. 
2. Если информации недостаточно задай не более 3 вопросов из `references/question-flows.md`.
3. Чётко разделяй:
   - факты;
   - допущения (assumptions);
   - варианты (options / alternatives);
   - решение (decision);
   - последствия (consequences).
4. Один ADR = одно решение. Если решений несколько, предлагай разделить их на несколько ADR.
5. Если пользователь назвал **конкретную технологию**, **сначала** проверь её в `assets/tech-radar.json`.
6. Если технология найдена и её `ring` = **`hold`**, **отвергни решение** и прямо скажи, что технология находится в статусе `hold` в `tech-radar.json` навыка.
7. Если технология **не найдена** в `assets/tech-radar.json`, **обязательно спроси**, нужно ли добавить её в `tech-radar.json` навыка. До ответа пользователя не считай её согласованной по радару.
8. Если технология имеет `ring = trial` или `assess`, допускай её только с явной пометкой о риске, ограничении области применения и необходимости дополнительного обоснования.
9. `tech-radar.json` — это ограничение и источник governance-контекста, но не замена архитектурному мышлению.

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

### Шаг 0. Проверка упомянутых технологий в `tech-radar.json`
До архитектурных вопросов проверь, назвал ли пользователь конкретные продукты, frameworks, brokers, databases, platforms или tools.

Если технология названа:
1. найди её в `assets/tech-radar.json`;
2. примени правила из `references/tech-radar-guide.md`;
3. только после этого переходи к формированию ADR.

### Шаг 1. Определи тип ADR
Сопоставь запрос с одним из типовых решений:
- выбор технологии (technology choice);
- интеграция (integration style / API / messaging / file exchange);
- данные (data design / storage / ownership);
- безопасность (security / IAM / compliance);
- развертывание (deployment / runtime / platform);
- build vs buy;
- архитектурный принцип или правило.

Если тип неочевиден, используй `references/question-flows.md`.

### Шаг 2. Задай минимум уточняющих вопросов
Задавай вопросы только о том, что меняет решение.
Обычно это:
- предмет решения;
- границы и затрагиваемые системы;
- драйверы решения (decision drivers);
- ограничения и стандарты;
- сроки или delivery pressure;
- ключевые quality attributes;
- варианты;
- риски и влияние на migration.

Нормальный объём — **3–5 сильных вопросов**, а не длинная анкета.

### Шаг 3. Подготовь ADR
Как только основы понятны, создай короткий draft по `assets/adr-template.md`.

Он должен содержать:
- заголовок;
- статус;
- краткий context;
- decision drivers;
- варианты с плюсами и минусами;
- предлагаемое решение;
- последствия;
- допущения и открытые вопросы.

### Шаг 4. Отдай draft на review
После короткого draft попроси проверить:
- корректность формулировки решения;
- полноту вариантов;
- не пропущены ли ограничения;
- реалистичность последствий;
- можно ли раскрывать draft в полный ADR.

Используй `assets/review-checklist.md`.

## Как задавать уточняющие вопросы

Руководствуйся `references/question-flows.md` и следующими правилами:
- задавай вопросы по важности для решения, а не по порядку разделов документа;
- предпочитай вопросы, на которые можно ответить коротко;
- там, где можно, предлагай варианты ответа;
- не спрашивай то, что уже можно вывести из контекста;
- не повторяй то, что пользователь уже сказал ранее.

Хорошие примеры:
- «Что именно выбираем: СУБД (database), способ интеграции (integration style) или границу владения данными (ownership boundary)?»
- «Что важнее: time-to-market, reliability, latency, cost или compliance?»
- «Есть ли ограничения по cloud, stack, data residency, support skills или стандартам безопасности?»

Плохие примеры:
- просить сразу заполнить все разделы ADR;
- задавать абстрактные вопросы без влияния на решение;
- требовать полный prose-текст до короткого draft.

## Правила для `tech-radar.json`

Используй `assets/tech-radar.json` в формате **Thoughtworks Build Your Own Radar**.

Ожидаемая форма:
- корневое значение — **JSON array**;
- каждый элемент — blip / entry;
- обязательные поля обычно включают:
  - `name`
  - `ring`
  - `quadrant`
  - `isNew`
  - `description`
- дополнительное поле `status` можно использовать для движения между ring.

Интерпретация `ring`:
- `adopt` — предпочтительный вариант по умолчанию, если он подходит по драйверам;
- `trial` — допустимо в ограниченном scope с явным описанием риска;
- `assess` — допустимо как исследуемый вариант, обычно не как массовый стандарт;
- `hold` — вариант должен быть отклонён.

### Правило для явно названной технологии

Если пользователь прямо называет технологию:
1. сначала проверь её в `assets/tech-radar.json`;
2. если `hold` — отвергни решение;
3. если записи нет — спроси, нужно ли создать дополнение к `tech-radar.json`; сформируй файл дополнения
4. до подтверждения не называй её «согласованной» или «рекомендованной» по радару.

### Как писать об отклонении

Если технология в `hold`, формулируй примерно так:
- решение в текущем виде отклоняется;
- причина — технология находится в ring `hold` в `tech-radar.json` навыка;
- предложи альтернативы из `adopt`, `trial` или `assess`, если они есть;
- отрази это в ADR как ограничение или как отклонённую альтернативу.

### Как писать о технологии, которой нет в радаре

Если технологии нет в `assets/tech-radar.json`:
- явно скажи, что она отсутствует в skill radar;
- спроси, нужно ли добавить её в `tech-radar.json` навыка;
- если работу надо продолжать сразу, зафиксируй это как open governance question.

## Требования к качеству ADR

Хороший ADR, созданный этим навыком:
- формулирует решение одной фразой;
- объясняет, почему вопрос возник сейчас;
- показывает реальные альтернативы;
- связывает аргументацию с decision drivers;
- честно отражает trade-offs;
- фиксирует последствия, включая негативные;
- определяет scope и impact;
- описывает migration / rollout, если это важно.

Слабый ADR обычно:
- описывает тему, но не решение;
- содержит только один вариант;
- скрывает компромиссы;
- смешивает несколько решений;
- не даёт понять, что делать дальше.

## Предпочтительный формат ответа модели

### Если данных мало
1. кратко сформулируй, какое решение ты видишь;
2. задай 3–5 вопросов;
3. если пользователь уже назвал технологию — сначала обработай `tech-radar.json`.

### Если данных достаточно для short draft
1. выдай короткий ADR по шаблону;
2. отдельно покажи assumptions и open questions;
3. предложи review по checklist.

### Если есть подтверждение
1. раскрой документ в полный ADR;
2. сохрани решение и основные trade-offs;
3. добавь детали implementation / migration / governance только там, где они уместны.

## Краткий чек-лист перед сохранением
Используй `assets/review-checklist.md` для проверки решения