specs/openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md

Spec Writing Profile

Профиль написания и ревью требований wealth-ledger-sdd-lab. Цель — одинаковое понимание поведения разными авторами, разработчиками и QA, а не дословно одинаковые документы. Это адаптация инженерных практик, не заявление о соответствии стандартам.

Scope

Автор и reviewer читают профиль перед подготовкой или согласованием Specs. Правила применяются к новым и изменяемым требованиям; весь canonical store ради стиля не переписывается. Пути, delta-операции и gates задаёт schema.yaml.

Specs определяют наблюдаемое поведение. Обоснования и открытые решения — в Proposal, межсистемные детали — в analysis/, механизмы — в design, способы доказательства — в QA. Ни один downstream-артефакт не вводит новое поведение молча.

Writing Rules

1. Основание. Каждое обязательство следует из согласованного намерения или существующего контракта. Наблюдение в коде, гипотеза и пример — не решение владельца. Неизвестное запиши в Open Decisions: вопрос, кто решает, зависимое требование и что блокируется. Несогласованные числа и варианты не становятся нормой. Для спорного или выведенного при анализе Requirement перед первым Scenario добавь **Источник (ненормативно):** — ссылку на конкретное решение Change Owner в Issue или пункт согласованной редакции контракта. Ссылка должна оставаться пригодной из canonical spec после archive; относительной ссылки на активный Proposal недостаточно. Источник объясняет происхождение, но не заменяет полную норму или approval; обоснование остаётся в Proposal.
2. Термины. Используй названия из затронутых canonical specs и предоставленного проектного глоссария. Один термин — одно значение в названном контексте. «Счёт», «брокерский счёт» и «учётная запись» не взаимозаменяемы. Новый или спорный термин определи в теле владеющего им Requirement; остальные требования ссылаются на него. Определение должно различать случаи, а не заменять слово синонимом. Общие термины передаются в глоссарий через Docs Impact; новый файл словаря на каждый change не нужен.
3. Атомарность. Один Requirement — одно независимо принимаемое обязательство. Если одну часть можно принять, а другую отклонить — раздели. Связанные условия, сохранность данных при отказе и единый атомарный результат остаются вместе. Число союзов или SHALL не определяет атомарность.
4. Явная норма. Назови субъект, условие применимости и наблюдаемый результат. Для нового обязательства предпочитай SHALL / SHALL NOT; существующие MUST / MUST NOT равнозначны и сохраняются. SHOULD / MAY не заменяют неопределённый исход: допустимая вариативность и исключения должны быть согласованы и описаны. «Корректно», «быстро», «при необходимости», «и/или», «и т. д.» без определения — повод уточнить правило. Краткость не оправдывает потерю условий.
5. Величины и границы. Для расчёта задай входы, формулу, знак, валюту, точность и момент округления, если они влияют на результат. Для периода — включительность границ, дату/время учёта и часовой пояс; для порога — сравнение и точку отсчёта. Различай ноль, отсутствие значения и неизвестный результат. Не добавляй допуск, таймаут или округление без источника только ради измеримости.
6. Свобода реализации. Описывай «что», а не внутренние классы, библиотеки или алгоритм. Если внутренний механизм можно заменить без изменения внешнего обязательства, это design. Внешний формат или протокол допустим в Specs, когда именно он является согласованным обязательством, а не удобством реализации.

Requirement and Scenario

Порядок блока: ### Requirement: с устойчивым именем → общая норма → нужные определения/таблица → #### Scenario:. Для новых требований используй короткое имя на русском; существующие headings сохраняй для native delta-сопоставления.

Выбирай форму по смыслу (адаптация EARS, не дополнительный синтаксис OpenSpec):

Смысл	Каркас нормы
Постоянное свойство	Система SHALL …
Реакция на событие	При … система SHALL …
Зависимость от состояния	Пока … система SHALL …
Ошибка или исключение	Если … система SHALL …

У ADDED/MODIFIED Requirement минимум один Scenario. GIVEN нужен, когда исходное состояние влияет на результат; WHEN задаёт событие; THEN — наблюдаемый исход с определённым ожидаемым значением или составом, не «работает правильно». AND продолжает предыдущий тип шага: дополняет исходный контекст, событие или ожидаемый исход. Шаги не описывают внутренние вызовы и селекторы UI.

Сначала общее правило, затем различающие примеры: основной путь, существенная граница, иной исход, отказ, повтор или конкуренция — по применимости. Каждый сценарий добавляет новый класс поведения. Не вводи правило только в Scenario и не переписывай правило целиком для каждой комбинации данных. Сценарии показывают следствия нормы, но несколько примеров не доказывают универсальный инвариант.

Representation

Когда прозы недостаточно	Представление и обязательные уточнения
Взаимодействуют несколько условий	Таблица решений: область входов, смысл «любое», политика совпадений (одна строка / первая / все), результат отсутствия совпадений или объяснение полноты
Результат зависит от истории	Переходы: исходное состояние, событие/условие, новое состояние, видимый эффект; существенные повторы и недопустимые переходы
Должно сохраняться свойство	Инвариант/формула с областью действия и единицами; примеры нуля, знака и округления по применимости

Нормативная таблица находится внутри Requirement до первого Scenario и вводится фразой с SHALL. Она — единственное определение правила, а не копия соседней прозы. Неоднозначные пересечения строк — дефект, если явно не задан приоритет или сбор результатов. Таблица безусловно не нужна каждому требованию. Внутренние состояния реализации и межсистемные схемы остаются в analysis/design.

Examples

Учебные примеры формы, не продуктовые решения WealthLedger. В реальном change периоды, состояния и исходы берутся из его согласованных входов.

Condition and Boundary

## ADDED Requirements

### Requirement: Отбор операций за календарный период
При формировании отчёта система SHALL включать все и только операции выбранного
счёта, дата учёта которых входит в выбранный период включительно по Europe/Moscow.

#### Scenario: Последний день периода и следующий день
- **GIVEN** выбран период 01.10.2026–31.10.2026 и счёт A
- **AND** на счёте A есть операции X с датой учёта 31.10.2026 и Y с датой 01.11.2026
- **WHEN** формируется отчёт
- **THEN** отчёт включает X и не включает Y

Плохо: «Система SHALL корректно отбирать операции до конца месяца» — не определены месяц, границы, дата отбора и счёт. «THEN список корректен» не позволяет проверить исход.

Decision Table

## ADDED Requirements

### Requirement: Различимость неполного и пустого итога
Система SHALL представлять итог расчёта по таблице. «Полнота» означает получение
всех данных выбранной выборки; «есть записи» — наличие хотя бы одной записи.
Оба условия логические. Совпадает ровно одна строка; «любое» означает оба значения.
Покрыты все комбинации.

| Полнота подтверждена | Есть записи | Видимый итог |
| --- | --- | --- |
| Нет | Любое | Недоступен, без числового итога |
| Да | Нет | Ноль и пояснение пустого результата |
| Да | Да | Рассчитанный итог |

#### Scenario: Известная часть не становится окончательной суммой
- **GIVEN** известна одна запись на 100 RUB, но полнота выборки не подтверждена
- **WHEN** пользователь просматривает результат
- **THEN** итог обозначен как недоступный, не показан ни как 100 RUB, ни как ноль

Плохо: строки «нет данных → 0» и «данные не полны → недоступно» без определения «нет данных» — одному входу могут соответствовать два разных результата.

State Transition

## ADDED Requirements

### Requirement: Отмена формирования отчёта
При запросе отмены система SHALL изменять состояние формирования отчёта по таблице.
Область правила — состояния «Ожидает», «Отменён», «Готов»; начальное — «Ожидает».
Совпадает ровно одна строка. Таблица определяет только событие отмены.

| До | После | Результат отмены |
| --- | --- | --- |
| Ожидает | Отменён | Отмена подтверждена, отчёт не будет сформирован |
| Отменён | Отменён | Отмена подтверждена без повторного эффекта |
| Готов | Готов | Отмена отклонена, готовый отчёт сохранён |

#### Scenario: Повтор отмены
- **GIVEN** формирование отчёта уже отменено
- **WHEN** пользователь снова запрашивает отмену
- **THEN** отмена подтверждена, состояние остаётся «Отменён»

Плохо: «повтор ничего не делает» — не определён результат для пользователя.

Review

Используй два прохода на существующем gate Specs (G2 или G3), не новый gate. Автор выполняет самопроверку; назначенный по режиму reviewer перепроверяет независимо.

Проход	Что проверить
Нормоконтроль	Native headings/операции; термины и единицы; явные субъект/условие/исход; атомарность; корректные ссылки; Scenario с проверяемым THEN
Смысл и набор	Необходимость и происхождение норм (у спорных/выведенных — источник действительно подтверждает норму, ссылка пригодна после archive); основной путь, альтернативы, отказы и границы; повторы/конкуренция/сохранность по риску; непротиворечивость таблиц и итогового baseline; отсутствие выдуманных решений

Проверь не только delta, но и получающийся набор вместе с canonical specs: сохранились ли действующие ограничения, исключения, инварианты и сценарии? MODIFIED заменяет полный блок; редакторское улучшение не разрешает удалить прежний сценарий или незаметно переименовать Requirement.

Профиль не отменяет ограничений установленного CLI. При предупреждении о длине сократи повторения или раздели действительно независимые обязательства; не убирай условия и не прячь норму в комментарий/код ради успешного --strict.

Контрольный вопрос: «Назови существенную ошибочную реализацию и наблюдение, которым это требование отличит её от соответствующей». Если ответ зависит от догадки, укажи точную неопределённость. Это эвристика ревью, не доказательство полноты.

Finding: файл/heading + цитата → нарушенное правило → два возможных толкования или недостающий исход → вопрос владельцу/адресат исправления. Reviewer возвращает находки, не переписывает текст по вкусу. Пример: «до конца месяца» → неясна правая граница → операция в последний день включается или исключается → уточнить в Specs. Нерешённый вопрос, меняющий требование или ожидаемый результат, блокирует его gate; косметическое предпочтение не блокирует. Validation и Findings — в существующем Gate Log, без нового отчёта на каждый Requirement.

Trial

Эффект профиля проверяется сравнительным пилотом; до результатов он не подтверждён.

1. До запуска зафиксируй четыре одинаковых для обеих версий задания: простое правило, ветвление, повтор/состояние и MODIFIED с исходной canonical spec. Для оценки отдельно запиши согласованные исходы, намеренно оставленные неизвестные и контрольные вопросы.
2. Сравни прежнюю и изменённую инструкции минимум на двух авторах/моделях, каждый выполняет обе версии. Сохрани входы, prompts, версии инструкций и моделей, доступные настройки и результаты. Для LLM используй отдельные сессии без ответов другой версии; для людей чередуй порядок версий, чтобы уменьшить эффект обучения.
3. Независимые читатели отвечают на одинаковые контрольные вопросы по полученным спецификациям, не зная автора и версии инструкции. Ответы для оценки из шага 1 раскрываются после чтения; согласие читателей само по себе не означает правильность.
4. По каждому заданию сравни расхождения трактовок, ошибки относительно согласованных исходов, пропущенные случаи, выдуманные нормы и время уточнения/ревью. Сохрани конкретные примеры ошибок вместе с результатами в Issue пилота.
5. Критерий улучшения согласуй до запуска: меньше смысловых расхождений без роста ошибок, пропусков и выдуманных норм; допустимое изменение времени определяет владелец. Если различий нет или данных недостаточно, эффект не подтверждён. Вывод ограничен проверенными заданиями и авторами/моделями. Совпадение формулировок и успешный CLI не считаются доказательством одинакового понимания.

Sources and Adaptation

Из девяти исследований sdd-spec-quality/*.md и трёх сводок result/*.pdf выбраны правила с понятной пользой для ручного Markdown-процесса. Первоисточники проверены 30.10.2026; критерии адаптированы, а не перенесены как обязательная сертификация.

Источник	Что взято и где предел
NASA SE Handbook, Appendix C, C.2–C.4	Необходимость, одна мысль, «что, а не как», проверяемость и согласованность; не сертификационный комплект документов
INCOSE GtWR v4 Summary, с. 2–3	C1/C3/C5/C7 для отдельного требования, C10–C14 для набора; R4/R7/R33–R36 — термины, величины, время. Полный платный Guide не заявлен как проверенный
EARS, автор методики	Каркасы условия/события/состояния/ошибки; русский язык — адаптация, не буквальная английская грамматика
RFC 2119, 8174 §2	Значения uppercase SHALL/MUST и запретов; наличие ключевого слова само по себе не гарантирует качество
Cucumber, Given/When/Then	Исходное состояние, событие, наблюдаемый исход; Markdown Scenario не становится исполняемым Gherkin-тестом

Из предложений не приняты: жёсткие лимиты слов/сценариев, подсчёт SHALL вместо атомарности, обязательные REQ-ID и скрытые атрибуты, JSON-first, новые линтеры и gates. Из нормоконтроля конструкторской документации заимствовано разделение проверки формы и смысла; соответствие ГОСТ, DO-178C или ISO/IEC/IEEE 29148 не заявляется. Таблицы и инварианты используются по риску; обязательная формальная модель каждому change не нужна.