review-specs

Files (2)

• SKILL.md
• review-template.md · references/

SKILL.md (first lines)

# Review Specs (Валидация спецификаций)

Проверить три спецификации — `feature-spec.md`, `functional-spec.md`, `ui-spec.md` — на согласованность, полноту и отсутствие противоречий. Результат: заключение «спецификации валидны» или список замечаний, сохранённый в файлы ревью.

Это итеративный процесс. После каждого прохода человек решает, нужно ли дорабатывать артефакты и запускать ревью повторно.

## Роли

- **AI-агент** — проводит анализ, формирует замечания, сохраняет файлы ревью
- **Человек** — утверждает заключение или направляет на доработку

## Иерархия документов

`feature-spec.md` — **базовый** документ. `functional-spec.md` и `ui-spec.md` — производные.

- Производные документы могут содержать детали, отсутствующие в базовом — это нормально
- `ui-spec.md` может отсутствовать для некоторых категорий задач
- Недопустимо: явное противоречие между базовым и производным документом
- Недопустимо: требование из базового документа полностью проигнорировано в производных

## Процесс

### Шаг 1 — Прочитать все три спецификации

Прочитать файлы в корне проекта:
- `feature-spec.md`
- `functional-spec.md`
- `ui-spec.md`

Если какой-то файл отсутствует — сообщить пользователю, какой именно, и остановиться. Ревью без всех трёх документов невозможно. Исключение - `ui-spec.md`, для некоторых категорий задач UI не требуется.

### Шаг 2 — Прочитать существующие файлы ревью (если есть)

Проверить наличие в корне проекта:
- `feature-spec-review.md`
- `functional-spec-review.md`
- `ui-spec-review.md`

Если файлы существуют — загрузить замечания из них. Это необходимо для группировки по актуальности на шаге 5.

### Шаг 3 — Провести анализ по четырём критериям

#### Критерий A — Покрытие требований

Для каждого требования из `feature-spec.md` убедиться, что:
- В `functional-spec.md` есть соответствующий модуль, поток данных или контракт
- В `ui-spec.md` есть соответствующий экран, компонент или состояние

Фиксировать: какие требования не отражены ни в одном из производных документов.

#### Критерий B — Сквозные сценарии

Для каждого пользовательского сценария из `feature-spec.md` проверить наличие полной цепочки:
- UI-экран (в `ui-spec.md`) → модуль/поток (в `functional-spec.md`) → интеграционная точка (сервис, хранилище)

Фиксировать: сценарии, у которых цепочка обрывается.

#### Критерий C — Полнота UI-состояний

Для каждого экрана/компонента в `ui-spec.md` проверить, что описаны состояния:
- `success` — штатный результат
- `error` — сбой операции или загрузки
- Граничные случаи: `empty`, `loading`, `offline` — если применимы к сценарию

Фиксировать: экраны с отсутствующими обязательными состояниями.

#### Критерий D — Отсутствие конфликтов

Искать явные противоречия между документами:
- UI ожидает поле / тип данных, которого нет в контрактах `functional-spec.md`
- `functional-spec.md` описывает поток, не имеющий точки входа в `ui-spec.md`
- Бизнес-правило в `functional-spec.md` противоречит поведению, описанному в `ui-spec.md`
- Любое требование `feature-spec.md` описано в производных документах иначе по смыслу

Фиксировать: каждый конфликт с указанием обоих документов и конкретных мест.

### Шаг 4 — Сформировать замечания

Каждое замечание оформлять по структуре:

```
**[ID]** [Критерий: A / B / C / D] — [Краткое описание проблемы]
- Документ: `[имя файла]`, раздел «[название раздела]»
- Серьёзность: [КРИТИЧНО] / [ВАЖНО] / [РЕКОМЕНДАЦИЯ]
- Описание: [Что именно не так]
- Связано с: `[другой документ]`, раздел «[название]» (если применимо)
```

ID формировать как `A-001`, `B-002` и т.д. (буква критерия + трёхзначный номер).

Классифицировать замечания по целевому документу:
- `feature-spec-review.md` — замечания к базовому документу (только критические конфликты, когда базовый документ неоднозначен или противоречив сам по себе)
- `functional-spec-review.md` — замечания к функциональной спецификации
- `ui-spec-review.md` — замечания к UI-спецификации

### Шаг 5 — Обновить файлы ревью

#### Если файлы ревью уже существуют

Сгруппировать все замечания (старые + новые) по актуальности:

```markdown
## Исправленные замечания

<!-- Замечания из предыдущего ревью, которые больше не воспроизводятся -->

## Актуальные замечания

<!-- Замечания из предыдущего ревью, которые остаются в силе, + новые замечания -->
```

Замечание считается исправленным, если при текущем анализе проблема не воспроизводится.

#### Если файлы ревью не существуют

Создать файлы с разделом «Актуальные замечания» (раздел «Исправленные» не нужен при первом проходе).

Использовать шаблон из `references/review-template.md`.

From YamiHilik/SDLCRoom, Apache-2.0.

More from YamiHilik/SDLCRoom